ConceptsIdempotency
Concepts
Idempotency
Retry any write without doing it twice.
Pilotv1
Every business-changing request needs an Idempotency-Key header: 8 to 64 of A-Z a-z 0-9 _ . : -. A UUID works. Missing or malformed is 422 OPERATION_KEY_REQUIRED, before anything runs.
| You send | You get |
|---|---|
| The same key and the same content | The first success again, same status and body, with Idempotent-Replay: true. Kept 7 days. |
| The same key and different content | 409 OPERATION_KEY_CONFLICT. The key stays bound to the first request. |
| The same key while the first still runs | 409 OPERATION_IN_PROGRESS. Retry the same request shortly. |
| A request that was refused (below 500) | The key is freed, so a corrected request can reuse it. |
Your own ids outlive the key
Operation keys protect one request for 7 days. Business events also carry your own durable ids, which make them happen once for good, under any key and after rotation: sourceEventId (an order or service), reference (a checkout hold), reversalId (a refund) and externalCustomerId (a customer). The same id with different content is a 409 conflict.