Key takeaways
- Idempotency makes repeated execution of one intended operation produce the same intended effect.
- Reuse the operation identity across retries, not across unrelated actions.
- The deduplication record and side effect need a consistent recovery design.
Overview
Network uncertainty makes retries unavoidable. A timeout may occur after the server has already completed an action. An idempotency key can identify one intended operation so a repeated request returns or reuses its result instead of applying it again. Key scope, retention, parameter matching and concurrency behavior are service-specific and must be documented.
How it works
Assign a stable identifier to one intended operation.
Persist the identifier and result atomically with the consequential change.
Recognize retries and return the prior outcome without repeating the side effect.
A timeout leaves the outcome uncertain
A client can lose the response after the server has already created a record or charged for an operation. Retrying as if nothing happened can repeat the effect. An idempotency key gives the server a stable way to recognize that the request is another attempt at the same intended action.
The exact contract matters. Services differ in key retention, parameter comparison, concurrency handling and whether they replay stored errors. Stripe’s documentation describes its own behavior; those details should not be assumed for every API. Read the service contract and keep the key with the job state so a process restart does not turn a retry into a new operation.
| Situation | Key decision | Reason |
|---|---|---|
| Retry after lost response | Reuse the same operation key | The intended action has not changed |
| A genuinely new purchase or create action | Use a new key | This is a separate authorized operation |
| Changed parameters under an old key | Follow the API’s conflict policy | The intent no longer matches the original request |
| Recovery after a crash | Load the persisted key and outcome | Avoid creating a duplicate operation identity |
Source material: Stripe — Idempotent requests ↓
Protect the gap between recording and doing
A system that marks a key complete before performing the effect can lose work after a crash. A system that performs the effect before recording the key can repeat work after a crash. Local transactional changes can often be recorded atomically, while external side effects need a recovery design that accounts for uncertain outcomes.
Use the external service’s idempotency support where available and retain operation receipts. An outbox or reconciliation process can help connect local state to external delivery, but it still needs a clear definition of completion. A unique database constraint alone does not automatically make an unrelated external message or purchase exactly once.
Test concurrent attempts and delayed retries
An illustrative CRM create request is submitted twice at the same moment with the same key. The result should be one intended record, with a documented response for both callers. Then test a crash, changed parameters and a retry after the service’s retention window. Each case exercises a different part of the contract.
Keep keys scoped to the correct account and operation so one tenant cannot collide with another or retrieve its result. Avoid using raw personal data as a key when a generated operation identifier will do. Measure duplicate effects and unresolved outcomes, not only how many requests the deduplication layer recognized.
What this looks like in practice
An integration times out while creating a CRM record. It retries with the same operation key; the server returns the existing result rather than creating a second contact.
Examples explain the concept; they are not reported customer results.What to check
Test concurrent repeats, changed parameters with the same key and retries after a process crash. Verify that the deduplication record and side effect cannot diverge.
Common mistake
Generating a new idempotency key on every retry or marking an operation complete before its external side effect is safely recorded.
Idempotency vs. Data deduplication
Idempotency prevents repeated execution of one intended action. Data deduplication reconciles records that already exist. It is safer to prevent duplicate side effects than rely only on later cleanup.
Read the Data deduplication definition →Questions answered
What is Idempotency?
Idempotency is the property that repeating an operation with the same intended input has the same intended effect as performing it once, helping systems retry safely without duplicating side effects.
Does idempotency mean the response is always identical?
The essential property concerns the intended effect. API-specific implementations may also replay a stored response; read the contract for exact behavior.
How long should keys be retained?
Long enough for the documented retry and recovery window. Retention is implementation-specific; a provider’s example should not be assumed to apply to every API.
Is idempotency the same as exactly-once delivery?
No. A request or event can be delivered several times while idempotent processing keeps its intended effect from repeating. Exactly-once claims need careful scope. A system may deduplicate a local state change without guaranteeing that every external side effect happens exactly once.
Can the same idempotency key be used forever?
Use the service’s documented retention and scope. A key may expire, and reusing it for a different operation can cause conflicts or return an old outcome. Persist one key per intended action and reconcile uncertain results before assuming a much later retry remains protected.
References and further reading
Primary documentation and source material for this topic. Sources checked September 14, 2026; provider requirements can change.
- Idempotent requests ↗Stripe
- Database constraints ↗PostgreSQL
Continue reading on the blog
Explore all articles and guides →Put the concept to work.
Explore the relevant AstroFabric workflow and see how the pieces connect.
Help keep this guide useful. Suggest a correction or browse the full glossary.