Idempotency

All POST endpoints support idempotency and ensure that operations are performed only once even if multiple requests are sent with the same request body.

Idempotency is critical when an API call has failed without an obvious reason that would potentially trigger a retry from your application. For example, if creating a payment fails due to a network error, you can safely create the payment again, passing the same idempotency key and assume the payment will occur exactly once, regardless of the number of calls.

An Idempotency-Key can be passed in the request header as any string up to 255 characters, although we recommend using UUID Version 4.

Creating multiple requests with the same idempotency key and request body will always return the same object as the first request instead of creating a new one. There is no validity period for idempotency keys.

If you reuse an idempotecy key to create the same resource again but with a different request body, you will receive an error similar to the following depending on the resource you are trying to create.

{
    "errorCode": "INVALID_REQUEST_DATA",
    "message": "Payment with given idempotency key was already created with different payload"
}

Did this page help you?