Idempotency

To ensure reliable and predictable interactions with our API, we support idempotency for certain operations. This feature allows you to safely retry requests without unintended side effects, such as duplicate transactions or resource creation. Below, we outline how idempotency is implemented and how you can use it effectively.

How idempotency worksCopy URL

1. Idempotency Key:

   • It is recommended you include an Idempotency-Key header in your non-GET API request.
   • The value should be a UUID (e.g., 550e8400-e29b-41d4-a716-446655440000).
   • This key uniquely identifies the request and ensures idempotent behavior.

2. Idempotent Behavior:

   • GET/PUT/HEAD requests are idempotent by default so can be retried in any case. POST and PATCH are not and need to be handled with idempotency-key.
   • For DELETE requests twice with same idempotency key then 204 HTTP status is returned, otherwise process the delete again
   • On successful request or 4XX the same response will be provided to the caller without processing the request again
   • An exception from the above are 429 HTTP status (too many requests) and 409 HTTP status (conflict) with error code “Processing” (indicates there are parallel requests to the same resource) which tell the user to try again later
   • On server errors the request will be processed again from the point it failed while not creating duplicate resources in the system

3. Storage:

   • When you send a request with an Idempotency-Key, we store the key along with:
     • The request body.
     • The response (after processing).
   • This data is retained for 30 days from the time of the initial request.

4. Request Matching:

   • If a subsequent request includes an Idempotency-Key that matches a previously stored key:
     • We compare the new request’s body against the stored request.
     • If they match exactly, we return the stored response without reprocessing the request.
     • If they do not match, we reject the request with a 409 Conflict status code, indicating that the Idempotency-Key is being reused with a different intent.

5. Expiration:

   • After 30 days, the stored idempotency key and its associated request/response data are automatically removed.
   • You can then reuse the same Idempotency-Key for a new operation, though we recommend generating fresh UUIDs for each unique request.

Why it mattersCopy URL

Idempotency ensures that retrying a failed or interrupted request (e.g., due to network issues) doesn’t result in duplicate actions. For example, if you’re initiating a payment, you can retry the request with the same Idempotency-Key and be confident that the payment won’t be processed twice.