Retries & idempotency
Recover from a lost response without creating a second order or repeating a payment.
On this page
Name the business request once
Supply Idempotency-Key on business creates and effectful POST commands. Authentication challenge, session, and renewal exchanges use their own single-use or session semantics and do not accept business-response replay. Generate one key per intended action and persist it before sending. Reuse that key when retrying the same action.
The idempotency namespace includes the tenant, integration client, HTTP method, normalized route, and key. Rotation of the API credential does not change the client namespace.
Idempotency-Key: booking-4387-create-orderUnderstand replay behavior
| Retry | Expected result |
|---|---|
| Same key, same request | Return the original authorized result without repeating the effect. |
| Same key, different request | 409 idempotency_conflict. Use a new key for a genuinely new action. |
| Concurrent request still running | Same result or 409 request_in_progress with retry guidance. |
| Key no longer authorized | Reauthorization fails. A cached response never bypasses access rules. |
A timeout is an unknown outcome
Do not assume a request failed to commit because your client lost the response. Retry using the original key, or look up the resource by your external reference.
For asynchronous work, keep the operation ID and poll its durable status. Retry a failed operation only when the response identifies it as retryable.
Retention is part of onboarding
Replay retention and financial deduplication follow your environment policy. Keep your original request keys and financial references for the applicable recovery window.
Read the agreed environment policy before relying on a recovery window. External-reference uniqueness remains useful after a request key expires.