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 prepared to gracefully handle additional members of the response.

Important

At large scale, systems might fail; upstream system could go down or degrade in performance, network connectivity might be unreliable or other unexpected errors might occur. Depending on the nature of the error, the system might get into an inconsistent state. If such an unexpected error occurs, we provide several mechanisms to recover from the error.

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 are not 503, should not be retried. To assist in safely retrying charges (without performing double bookings) it is advised to provide an idempotency key for every charge request. The idempotency key is a unique identifier for a single request. For example, if a charge request is sent with the same idempotency key and the same HTTP body two times in a row, it is considered as one request. This makes it possible to easily and safely retry charges while preventing double bookings. Read more in the Idempotency guide.

To protect the API from being overloaded, the number of requests per second is limited. After that threshold is reached, the API will start responding with HTTP response 429 Too many requests.