services / email / cloud / 2.0 / general

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:

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"
}

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.