Idempotency
Send the same Idempotency-Key when you retry, and nothing happens twice.
A network error can leave you unsure whether a request arrived. Retrying a payment or a payout blindly could charge or pay twice. The Idempotency-Key header makes the retry safe. It is required on every POST that creates or moves money: create payment, create attempt, create payout and cancel payout.
- Choose a new key for each thing you mean to do: 1 to 255 printable ASCII characters. A UUID, or your order id plus the action, works well.
- Keys are kept for at least 24 hours, per project.
- Retry with the same key and the same body and you get the first answer's status with the object as it stands now. The response carries
Idempotent-Replayed: true. Nothing is created or sent again.
| Situation | Answer |
|---|---|
| No key on a POST that needs one | 400 idempotency_key_required |
| Same key, different body | 422 idempotency_key_reused. Use a new key for a new request. |
| The first request is still running | 409 idempotency_key_in_progress. Retry with the same key after a moment. |
Your own reference on a payment is separate: it is your order id, unique in the project. Reusing it with a new key answers 409 duplicate_reference and names the existing payment.