Idempotency & retries
Retry one business intent without creating a second one.
Keep the business identity stable
When an operation requires idempotency-key, generate a unique key for that business intent and keep both the key and canonical payload unchanged on retry. Key scope, permitted format, retention, stored response behavior, and conflicts come from that operation’s contract.
A retry with the same scoped key and a different canonical payload is a conflict, not a request to update the original operation. A new key can represent a new business action, so do not rotate keys merely to clear a timeout.
Handle uncertain outcomes
A disconnected request may already have committed. Use the operation’s documented replay or read path to reconcile before issuing a new intent. Honor Retry-After and bounded backoff where supplied. Authentication retries and business idempotency are independent: single-use credentials still need a fresh token for each attempt.
Do not assume one platform-wide window
The reference renders exact idempotency metadata where committed. Read-only, intrinsically idempotent, and explicitly keyed operations have different behavior. Missing metadata is not a promise of durable replay.