Error Handling

We follow the error response format proposed in RFC 7807, also known as Problem Details for HTTP APIs. As with our normal API responses, your client must be ready to handle additional fields in the response.

Important

At a large scale, systems might encounter failures; upstream systems could go down or degrade in performance; network connectivity might be unreliable, or other unexpected errors might occur. Rest assured, depending on the nature of the error, the system is equipped with several mechanisms to recover from the error, ensuring the safety and integrity of your operations.

When the API returns an error with HTTP status code 503, the failed request should always be retried. Any other HTTP status code in the 5xx range that is not 503 should not be retried. To assist in safely retrying charges (without performing double bookings), it is highly recommended to provide an idempotency key for every charge request. The idempotency key, a unique identifier for a single request, is a powerful tool that ensures the prevention of double bookings, giving you the confidence to retry charges without any worries. Read more in the Idempotency guide.

The number of requests per second is limited to protect the API from being overloaded. After reaching that threshold, the API will start responding with HTTP response 429 Too Many Requests.