Error handling was something we took very seriously when designing our API. This helps achieving integrations that are robust and applications that present meaningful error messages to the end-users.

​
Comprehensive list

All possible error scenarios are enumerated as part of the OpenAPI spec, resulting in a comprehensive list of error codes and messages. You may see these errors on every endpoint’s page, by cycling through the different HTTP status codes in the response examples.
Core Data Model

For a comprehensive list of all possible scenarios, per API endpoint, check all the possible HTTP status codes...

Core Data Model

... as well as all the potential errors that may be contained under that HTTP status code.

​
Consistent shape

Our API follows a consistent approach to describe errors. Every error response includes a standard payload with the following fields: 
{
  // A code that identifies the error.
  "code": "country_not_supported",
  // A developer readable message describing the error.
  "message": "The country is not supported",
  // Additional details about the error.
  "details": {}
}

​
HTTP status codes

Every error response includes an HTTP status code to indicate the nature of the error. Here are some of the most common status codes you might encounter:
  • 400 Bad Request: The request is malformed or didn’t pass validation according to the endpoint’s OpenAPI schema.
  • 401 Unauthorized: The request is missing authentication credentials or the provided credentials are invalid.
  • 403 Forbidden: The request is authenticated but doesn’t have the necessary permissions (token scopes) to access the resource.
  • 404 Not Found: The requested resource doesn’t exist.
  • 409 Conflict: The request failed due to a business logic error.
  • 429 Too Many Requests: The client has sent too many requests in a given amount of time and is being rate-limited.
However, the code field in the error payload is where you primarily should look as it provides a more granular description of the failure.