5xx after the server has already processed it, leaving you unsure whether to retry. Idempotency keys make retries safe: repeat a request with the same key and the Payouts API returns the original result instead of performing the operation a second time.
Using an idempotency key
Send anIdempotency-Key header on any POST request:
- Idempotency applies to
POSTrequests only.GET,PATCH, andDELETEare already idempotent by nature and ignore the header. - Use a unique value per logical operation. A version 4 UUID is a good choice.
- Reuse the same key when retrying the same operation; use a new key for a genuinely new operation.
Generate the key on your side before sending the request and keep it with the operation you are performing. If a request fails, retry with the exact same key so the server can recognize it as the same operation.
How keys are scoped
A key is not global. It is scoped to the operation it was first used for, which means the same string used against a different endpoint (or, for multi-tenant integrations, a different business) is treated as an independent operation. In practice you don’t need to worry about accidental collisions between unrelated calls, but you should still generate a fresh key per operation. Idempotency records are retained for 24 hours. After that window a key is forgotten and reusing it starts a new operation.Replayed responses
When a request with a previously seen key succeeds, the API stores the response. Retrying with that same key returns the stored response verbatim, with the same HTTP status code, plus a header marking it as a replay:Reusing a key with a different body
A key is bound to the body of the request it was first used with. Reusing it with a different body is almost always a bug (a mismatched retry, or an accidentally reused key), so the API rejects it rather than guessing your intent:
Retry with the original body, or use a new key for the new operation.
Concurrent retries
If you send a second request with the same key while the first is still being processed, the API does not run the operation twice. It briefly waits for the first request to finish and then returns its result. If the original request is still not finished by the time the wait elapses, you get:Failed requests can be retried
Only successful outcomes are stored. If a request fails with a client error (a4xx), that outcome is not cached, so you are free to fix the problem and retry with the same key. This is why a corrected retry after a validation error works as expected.
When a key is required
Some endpoints require an idempotency key. If you omit it on one of those, the request is rejected:If the idempotency store is unavailable
To guarantee that an operation is never accidentally duplicated, the API will refuse a request rather than process it without idempotency protection when the store is temporarily unavailable:
Retry after a short delay with the same key.
Summary
For the full error model, see Errors. For the HTTP status codes, see Status Codes.