HTTP/1.1 401 Content-Type: application/problem+json X-Uniserv-Request-Id: bde243a201faabfd { "status": 401, "type": "https://docs.uniserv.com/email/cloud/2.0/general/problems#no-auth-data", "title": "No authorization header present" }
Errors and Troubleshooting
The REST API uses HTTP status codes to signal error conditions, which fall into two broad categories:
-
4xx
: client errors (missing credentials, invalid format, etc.) -
5xx
: server errors (internal server issues)
In case of client errors, repeating the exact same request will not yield a different result, whereas for server errors, retries after some time are possible and permitted.
In addition to status codes, the API returns JSON payloads for error conditions in problem+json format:
The status
is the HTTP status code, the title
provides a short human-readable
description for developers, and the type
is a URI that points to a description of the error and possible solutions.
Uniserv assigns a unique identifier for each request (both successful and failed) and returns
it in the response as a X-Uniserv-Request-Id
header. When contacting support, please always include this
request ID.
Error Types
400: Field Validation Error
The given JSON document is missing required input fields or there was invalid data inside
one of the fields. The violations
attribute inside the response will give detailed information
about the fields or url of fields that didn’t pass validation.
In this example, there was no email address given in the request, which is mandatory:
{ "status": 400, "type": "https://docs.uniserv.com/email/cloud/2.0/general/problems#field-error", "title": "Field Validation Error", "violations": [ { "message": "must not be blank", "fieldName": "email" } ] }
401: No Auth Data
Authentication failed because the request didn’t contain a valid Authorization header. Requests to /validate need to include a valid API key. Make sure to include the header in the following format:
Authorization: Bearer YOUR-API-KEY-HERE
401: Credentials are invalid
An Authentication header was present and the format was correct, but the given credentials were invalid. Please log into Uniserv CONNECT and check your credentials.
401: API Key Invalid
An Authentication header was present and the format was correct, but the given API key was invalid. Please log into Uniserv CONNECT and check your API key.
For more information see API Key
401: Origin Invalid
The Origin
header in the request didn’t match any of the whitelisted domains in your
account. This error typically occurs when calling the Autocomplete API from a user’s
browser.
For example, if you serve your address input form at https://example.com/signup
, your
users' browsers will send the following Origin
header to Uniserv:
Origin: https://example.com
In this case make sure that example.com
is in the list of permitted domains. You can
configure the list of domains in Uniserv CONNECT.
403: Account Disabled
The account has been disabled. In case you have multiple accounts, please make sure you use the API key of an active account. Please contact support in case you need to re-enable the account.
403: Service Disabled
The API you called is disabled in your account, most likely because your plan doesn’t include the functionality.
403: Feature Disabled
The API you called is disabled in your account. This may happen, for example, if you attempt to call the Autocomplete API, but your current plan only includes address validation.
403: Quota Expired
This error is raised if you are on a prepaid plan where you purchased a fixed number of requests for a given period of time, which has now passed. Note that there may still be requests available on that plan, but the requests are not usable because the plan has expired.
403: Quota Exhausted
You have exceeded the number of requests included in your prepaid plan. Please check request statistics and logs in Uniserv CONNECT to see when and how your requests have been spent.
Uniserv sends an email notification when the number of requests reaches 75% to warn you ahead of time.
404: Not Found
The requested URL has not been found, please check your base URL and endpoint configuration. Valid endpoints are as follows:
-
https://api.uniserv.com/email/v2/validate
405: Method Not Allowed
Please send an HTTP POST request. Other HTTP methods like GET, PUT, or DELETE are not supported by the API.
415: Unsupported Media Type
The API expects a body in JSON format, which needs to be declared using the Content-Type
header:
POST /email/v2/validate Content-Type: application/json Authorization: Bearer <your-api-key-here> { ... }
429: Too Many Requests
You have exceeded the number of requests per second that are permitted for a single account on one particular endpoint. Please contact support if you need to increase the limit.
Endpoint | Ratelimit (Requests / Second ) |
---|---|
real-time validation |
15 RPS |
500: Internal Error
The request failed due to an internal error on the server side. You may repeat the request as-is or contact support if the issue persists.
500: Country not available
The request failed due to the requested country processing module not available at this moment or not supported at all.