Concepts
Idempotency
Idempotency-Key on every POST, and why it is mandatory on payouts.
Send Idempotency-Key: <unique string> on any POST. It is required on
POST /v1/payouts — a retry without one can send funds twice, so the API
rejects the request with 400 idempotency_key_required rather than let you find
out expensively.
| Situation | Result |
|---|---|
| First use | request executes, response stored |
| Same key, same body | the stored response replays, with Idempotent-Replay: true |
| Same key, different body | 409 idempotency_key_reuse |
| Same key while the first is still running | 409 idempotency_in_progress + Retry-After |
Keys expire after 24h. Use a UUID, or something derived from your own record id.
A 5xx or a network timeout does not mean the request failed — only that you did not see the answer. Retry with the same key.