Pattern
Give a retryable mutation one stable operation ID
A retry should mean 'finish this operation,' not 'please create another one.'
When it fits
- A create or update request may be retried after a timeout, dropped connection or transient service error.
When to avoid it
- Do not assume idempotency exists where the service does not guarantee it, and do not reuse one key for materially different requests.
What to look for
A retry should mean 'finish this operation,' not 'please create another one.'
Why it matters
Attach a stable idempotency or request key to one logical mutation and reuse it for retries of that same intent. Generate a new key only for a genuinely new operation. Store enough context to recognize ambiguous responses and reconcile them. This is especially valuable for payments, job creation, provisioning and bulk actions where duplicates are expensive.
An example
If a create-order call times out, retry with the same operation ID rather than issuing a second independent create request.
Check your result
Repeated delivery of the same logical request cannot silently create multiple intended-once effects under the API contract.
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.
Connected ideas
Useful withTreat a timeout as an unknown outcome
Evidence and sources
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