Error Handling

Oh no!

Error Handling and Status Codes

The API returns the appropriate HTTP status code for each request, which can be used to categorize the most common types of errors. Some of the supported status codes include:

• 400 (Bad Request)

• 401 (Unauthorized)

• 402 (Payment Required)

• 403 (Forbidden)

• 404 (Not Found)

• 405 (Method Not Allowed)

• 406 (Not Acceptable)

• 409 (Conflict)

• 418 (I'm a teapot – yes, really!)

• 422 (Unprocessable Entity)

• 429 (Too Many Requests)

• 500 (Internal Server Error)

• 502 (Bad Gateway)

• 503 (Service Unavailable)

• 504 (Gateway Timeout)

For additional details, you can refer to the error, error_description, and errors fields in the response for a deeper understanding of the issue.

---

Common Error Causes

• HTTP 400 errors: These typically occur when a request is missing a required parameter, includes an unsupported parameter or value, repeats the same parameter, or has a malformed structure. Most of these errors return the INVALID_REQUEST code, with additional details in the errors array.

• HTTP 422 (Unprocessable Entity): This error is often caused by a semantic (logical) issue, indicating a problem within your integration (e.g., a mismatch in expected values or business logic).

---

As the API evolves, we may introduce more specific error and status codes. For now, treat all status codes in the 200-299 range as successful responses, and any codes in the 400+ or 500+ range as errors.

Given that our API has over 1000 unique error codes grouped by HTTP status, we recommend avoiding the implementation of individual error codes in your customer-facing interface. Instead, we suggest handling them with a catch-all clause for each HTTP status code.

Notes

• Errors can be shown directly to the customer using the error_message, while more specific details explaining the problem will be provided in the errors object.

• We recommend providing a combination of error_message and error_reference when communicating with the customer and API support.