Networks fail. Every POST, PATCH and DELETE must carry an Idempotency-Key header (1–255 printable ASCII characters) so you can retry it safely. The only exception is POST /webhook-endpoints/{id}/test, which is harmless to repeat.
| Situation | Response |
|---|---|
| First request with a key | Processed normally. |
| Same key, same method, path and body | The original status and body, with Idempotent-Replayed: true. Nothing runs twice. |
| Same key, different body | 409 IDEMPOTENCY_CONFLICT — use a new key for a new request. |
| Same key while the first is still running | 409 OPERATION_IN_PROGRESS (retryable) — retry after a short wait. |
Stored outcomes: successful responses and deterministic errors (400, 404, 409 CONFLICT, 410, 422). Not stored, so you can retry with the same key: 401, 402, 403, 409 OPERATION_IN_PROGRESS, 429 and 5xx. Keys are kept for 30 days per partner and mode. A different key of the same partner may replay a stored response only if it can see the resource.
Choosing keys
Derive the key from your own record, for example order-1042-line-2-activation. Never use a random key per attempt — that defeats the purpose.
Business references that last
Idempotency keys expire; business references do not. For activations and other service changes also send external_request_id (unique per intended action, kept permanently: the same id with the same request returns the original operation, with a different request 409 CONFLICT) and external_order_reference (your order number; not unique, several devices of one order can share it).
"secret": null.