Errors

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.

​

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.