services / location / 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/location/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, an invalid country code was given and several fields were missing:

{
    "status": 400,
    "type": "https://docs.uniserv.com/location/problems#field-error",
    "title": "Field Validation Error",
    "violations":
    [
        {
            "message": "Invalid country code",
            "fieldName": "country"
        },
        {
            "message": "Both postalCode and locality must be set if localityLine is not set.",
            "fieldName": "localityIdentificationSet"
        }
    ]
}

401: No Auth Data

Authentication failed because the request didn’t contain a valid Authorization header. Requests to /start-session and /validate need to include a valid API key. Requests to /autocomplete need to include a valid session token. Make sure to include the header in the following format:

Authorization: Bearer YOUR-API-KEY-HERE

or

Authorization: Bearer YOUR-SESSION-TOKEN-HERE

In case of a session token, please make sure that the country in your request matches the country you have issued the session token for.

For more information see API Key

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.

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.

401: Missing Session Token

All autocomplete requests require a session token, but none was included in the request. Please create a token using the start-session endpoint and include it in the Authorization header of each autocomplete request.

Authorization: Bearer YOUR-SESSION-TOKEN-HERE

401: Invalid Session Token

The autocomplete session token could not be decoded. Please make sure to use the token from the start-session endpoint verbatim.

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.

403: Expired Session Token

The Autocomplete API session token has expired. Please create a new session and repeat the request with the new session token.

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/location/v1/validate

  • https://api.uniserv.com/location/v1/start-session

  • https://api.uniserv.com/location/v1/autocomplete

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 /location/v1/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. Uniserv is using the following per-customer limitations:

Endpoint URL Ratelimit (Requests / Second )

/location/v1/autocomplete

60 RPS

/location/v1/start-session

30 RPS

/location/v1/validate/validate

30 RPS

/location/v1/validate/batch/sync

90 RPS

Please contact support if you need to increase the limit.

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.