Pattern
Keep the operation key within its contract
Reuse one key for retries of the same intended change. First check what the API promises: a repeated key only helps when the service still recognizes it.
Before you use it
- Use when
- A create or update request may be retried after a timeout, dropped connection or transient service error.
Keep this limit in mind
- Do not assume idempotency exists where the service does not guarantee it, and do not reuse one key for materially different requests.
Current editorial reading
Keep identity and intent together
Store the key with the request parameters and result or unresolved status. Retry with that same identity after an ambiguous response; do not silently generate a second create request. Give a genuinely new operation a new key, and never reuse a key for changed parameters. Check which endpoint, account or other scope the service uses to recognize duplicates.
Check the lifetime before replay
Find the service's retention rule and what happens after it expires. Stripe, for example, may treat reuse of a pruned key as a new request; it also returns saved failures for recognized retries. A stable key therefore does not promise eventual success or indefinite duplicate protection. If recognition is uncertain, reconcile the original outcome before deciding whether to issue another mutation.
Take it with you
For one timed-out request, locate its saved key and parameters, verify the service's recognition window, and choose a same-operation retry or an authoritative status check.
Sources and evidence (2)
What we checked
Amazon describes caller-provided request identifiers and parameter checks to distinguish a retry from a different intent.
Selected official passages read on 2026-10-04. This is an API contract pattern, not a guarantee for endpoints that do not implement it.
Making retries safe with idempotent APIs · Reducing client complexity; Same client request ID, different intent
Retention requirements for recognizing earlier requests vary by service and resource.
Selected official passages read on 2026-10-04. The card does not transfer EC2 retention semantics to other APIs.
Making retries safe with idempotent APIs · Late arriving requests and the life span of unique client request identifiers
Stripe returns a stored result for a recognized key, including failures, and may create a new request after the original key is pruned.
Official API page selected passages read on 2026-10-04. Stripe-specific behavior is an example; readers must inspect the contract of their own endpoint.
Idempotent requests · Idempotent requests: saved results, key pruning and parameter comparison
Editorial sources (2)
Save and practise this idea
My learning
Read. Recall. Repeat.
Save this idea and return to it on any device.
Keep exploring
Connected ideas
You are readingKeep the operation key within its contract
Ideas that link here
These ideas link to this one. Check their conditions and limits before use.
Useful with this ideaRetry slower, with randomness, and stop
Original edition evidence and sources
These records belong to the original released edition. The current editorial reading has its own evidence above; neither set silently replaces the other.
Amazon and Stripe document idempotency keys or request identifiers as a way to safely retry a mutation without unintentionally performing the same logical operation twice.
Idempotency semantics depend on the API contract and retention window; callers must not assume every endpoint supports them.
Making retries safe with idempotent APIs · Client request identifiers and retry safety
All sources (1)
Original edition, downloads and provenance
The reading above is editorial version 1.0.0, bound to this exact source edition. The original data and saved downloads retain that edition and the separate editorial layer. They may contain earlier wording; use the current reading above when interpreting it.
Version 0.1.0
No review details are supplied for this edition.
Read the original edition and overlay as JSON · Release details