Idempotent Workflows
Make retries and duplicate delivery converge on one durable business outcome.
2–5 minute refresher
Timeout→Backoff→Jitter→Retry budget→Circuit breaker→Load shedding
One logical intent → one stable identity → one recorded outcome
30second
refresher
refresher
An idempotent workflow assigns a stable identity to one logical operation and records its durable outcome. Repeated attempts return or continue that same outcome instead of applying the effect again.
What problem does it solve?
Timeouts and at-least-once delivery make duplicates unavoidable. Without operation identity, the server cannot distinguish a retry from a new request.
How it works
- Generate an idempotency key at the edge where user intent begins.
- Atomically claim the key and record request parameters.
- Apply the business state transition once.
- Persist the result and any outgoing message in the same commit boundary.
- Return the recorded result to duplicates and retain it for the full retry horizon.
Decision guide
Key trade-offs
| Choice | What you gain | What it costs |
|---|---|---|
| Long retention | Safe delayed retries | Storage and index growth |
| Parameter binding | Prevents key reuse for different intent | More validation state |
| Natural idempotency | Less deduplication storage | Not possible for every side effect |
What happens if?
The service crashes after charging but before replying
A retry with the same key must recover the recorded charge outcome. If the external provider is involved, pass the same identity downstream or reconcile provider state before attempting another charge.
Where it appears
- Payment APIs
- Transactional outbox
- Job schedulers
- Event consumers
Senior interview modeWhy is checking for a key and then performing the write in two transactions unsafe?Show answer
Concurrent attempts can both observe no key and apply the effect, or a crash can apply the effect before the key is recorded. The claim and effect need one atomic boundary.