Skip to main content
Network failures happen. If a request times out, you can’t tell whether it was processed. An idempotency key lets you retry without the risk of doing the same thing twice.

Send an idempotency key

Add an idempotency-Key header to any POST or PUT request. The header is optional. Use a unique value for each operation, such as a UUID.

How it works

  • If you send the same key again within 24 hours, you get the saved response from the first request. The operation isn’t run a second time.
  • If you reuse a key with a different request body, the request fails with 409 and the error code idempotency_conflict. Send the identical body to replay the original response, or use a new key for a new operation.

When to use it

Send an idempotency key whenever you retry a request that changes state, such as creating a charge, refund, or payout. Use the same key for every retry of the same operation. For 429 and 5xx responses, retry with exponential backoff. See Errors and conventions.
Idempotency keys are available on API version 1.2.
Last modified on November 10, 2026