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. 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.

3. 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.

4. 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.