Using the API
Idempotency keys
A network failure can leave you not knowing whether a request took effect. Send an Idempotency-Key header and you can safely send the same request again.
How it works
The server runs a request once and answers every repeat that carries the same key with the first answer. A repeat is marked with the header Idempotent-Replayed: true.
| Rule | Value |
|---|---|
| Header | Idempotency-Key: <1 to 255 printable ASCII characters> |
| Where it is required | POST /v1/refunds, /v1/payouts, /v1/payout_batches, /v1/conversions, /v1/saved_addresses |
| Where it is recommended | Every other POST |
| Where it is ignored | GET, PATCH, DELETE |
| Scope of a key | The merchant, the mode, the method and the path |
| Kept for | 24 hours from the first request |
| Same key, same body | The stored response is returned again, with the header Idempotent-Replayed: true |
| Same key, different body, method or path | 422 idempotency_ |
| Same key while the first is still running | 409 request_in_progress with Retry-After: 1 |
| What is stored | Any answer produced after the request began to execute: 2xx, a 4xx raised by a business rule, a 5xx |
| What is not stored | 401, 403 insufficient_scope, 429, 400 raised before execution (bad JSON, unknown parameter), request_in_progress |
Where the key is required
Five calls are refused without it, with idempotency_key_required, because a duplicate of any of them is a second request to move money:
On every other POST it is recommended: a duplicate order or session is a nuisance, not a loss. GET, PATCH and DELETE ignore it, because they are already safe to repeat.
What a repeat answers
- Same key, same body. The stored response, again.
- Same key, different body, method or path.
idempotency_key_reused, status 422. - Same key while the first is still running.
request_in_progress, status 409, withRetry-After: 1.
When the outcome is unknown
If a call times out on your side, or answers 504 with outcome_unknown, the request may or may not have taken effect. Send it again with the same key.
Never invent a new key for a retry of a money-out request
A new key makes it a second request. While a payout is unknown, the same key cannot make another payout however long ago it was first used: the 24-hour life of a key does not apply to it. A timeout is an unknown outcome, not proof of failure.