Response status codes

Under Responses, you can see the possible HTTP status codes that will be returned together with a response message.

  • If the API returns a status code of "200", it means your request was successful. You can see an example of a successful response, as well as the model.
  • If the API returns any other code, it means there was an error.

The table below will help you identify the reason why you are getting a certain response.

HTTP status code Title Scenario
200 Success You've submitted a successful request and a valid response was returned. Your request may contain confidence level or corrections. This is the only chargeable response code.
400 Bad Request You didn't specify the email field. Try submitting another call and make sure the request body contains the email field.
You've specified an email value that is too long. Try submitting another request and make sure the email address you specify contains a maximum of 254 characters.
You've specified an unsupported timeout value. Try submitting another call and make sure you specify a timeout value that is between 3 and 15.
You didn't provide an authentication token. Try submitting another request and make sure you specify your token, which you can find by signing in to the Self Service Portal.
You've submitted a malformed request body. Try sending another call and make sure the request body contains all required fields and that they are formatted correctly.
You've submitted an empty request body. Try sending another call and make sure the request body contains all required fields.
You've submitted an invalid Reference-ID header. Try submitting another request and make sure this header is formatted correctly.
You've submitted an invalid Add-Metadata header. Try submitting another request and make sure this header is formatted correctly.
401 Unauthorized The authentication token you've provided is incorrect. Sign in to the Self Service Portal to find the right token.
403 Forbidden The authentication token you've provided is valid, but it's associated with another product or you have insufficient credits. Sign in to the Self Service Portal to check if you are using the right token and if you have credits.
The authentication token you've provided is disabled. Sign in to the Self Service Portal to activate the token.
The domain you've sent the request from does not have access to your integration. Sign in to the Self Service Portal to whitelist the domain.
The IP address you've sent the request from does not have access to your integration. Sign in to the Self Service Portal to whitelist the IP address.
404 Not Found The resource you've requested could not be found. Try submitting another call and make sure you're using the correct endpoint URL. If the issue persists, contact support.
406 Not Acceptable You've specified an invalid Accept header. Try submitting another call and make sure you specify a valid Accept value. Check out Supported data formats for details.
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 support.
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. Check out Supported data formats for details.
429 Too Many Requests You've submitted too many requests. To protect all customers, your account has been temporarily throttled. Check out Rate limiting for details.
500 Internal Server Error An unexpected server error was encountered. Try submitting another request. If the issue persists, contact support.
503 Service Unavailable The service is currently unavailable. You can check the API's uptime and downtime by going to the service status page.