Status codes and error responses

The following response codes can be returned by the API:

Status Code Reason phrase Description
200 Success Request processed successfully.
204 No Content Request processed successfully, but there is no content to be returned.
400 Bad Request
  • Request failed due to malformed syntax.
  • When an element is present in the "locality_lookup" or "postal_code_lookup" array that is not part of the available elements for the country;
  • When "locality_lookup" and "postal_code_lookup" are both defined;
  • If "locality_lookup" or "postal_code_lookup" is defined with a different aggregation;
  • A subset of values should be defined as the minimum - "town" needs to be specified for locality lookup and "postal_code" is required for postal code lookup – otherwise we get Bad Request;
  • "max_suggestions" value is out of range.
401 Unauthorized Auth-Token provided is incorrect. Sign in to the Self Service Portal to find the right token.
403 Forbidden Request is not authorized to use this service.
404 Not Found Request is not found.
406 Not Acceptable Request is not in an acceptable format.
408 Request Timeout Your request has timed out (the web server failed to respond in the specified time frame). Try submitting another request. If the issue persists, contact us.
415 Unsupported Media Type You've specified an invalid Content-Type header. Try submitting another call and make sure you specify a valid Content-Type value.
429 Too many requests Too many requests were sent. To protect all customers, your account has been temporarily throttled. Check our rate limiting for more details.
500 Internal Server Error An unexpected server error was encountered. Try submitting another request. If the issue persists, contact us.
503 Service Unavailable Service unavailable. Check service status for up-to-date information.

Error response

Successful API request returns the response within a result object. However, should an error occur, an error object is returned instead with the below fields.

Name Type Description
type string A link to documentation that provides more details about the error you've encountered.
title string The title of the error.
detail string A description of the error.
instance string The endpoint that returned the error.