Idempotency protects against duplicate transactions when network issues or errors cause you to retry API requests. By including a unique identifier with your requests, you can safely retry operations without worrying about creating duplicate payments or resources.
Why use idempotency?
Network timeouts and connection issues are common in API integrations. With idempotency, you can confidently retry failed payment requests knowing they won't be processed twice, protecting both you and your customers from duplicate charges.
Example scenario: Your payment request times out due to a network issue. Instead of wondering if the payment went through, you can safely retry with the same Idempotency-Key and either get confirmation of the original payment or have it processed if it failed.
What you need to know
Adding an Idempotency-Key
For POST, PATCH, and DELETE requests, include an Idempotency-Key header with a unique UUID:
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
GET and PUT requests are naturally idempotent and don't require this header.
How it works
When you send a request with an Idempotency-Key, we store the key along with the request body and response for 30 days.
Request matching:
- If you retry with the same key and identical request data, we return the original response without reprocessing
- If you reuse a key with different request data, we return a
409 Conflicterror
Response behavior
- Successful requests (2xx) or client errors (4xx): Same response returned without reprocessing
- Rate limiting (429) or processing conflicts (409): Retry allowed as these are temporary conditions
- Server errors (5xx): Request reprocessed to complete the operation, preventing duplicate resources
- DELETE requests: Return
204status when retried with same key
Key expiration
After 30 days, idempotency keys and their associated data are automatically removed. You can then reuse the same key, though we recommend generating fresh UUIDs for each unique operation.