Idempotency
Why a lost acknowledgement makes every retry a possible duplicate, and how idempotency keys, atomic recording and retention turn at-least-once into exactly-once effects.
25 min7 steps
By the end you can
- Explain why a timeout cannot reveal whether an operation happened, and estimate the duplicates a naive retry causes
- Distinguish naturally idempotent operations from ones that need deduplication
- Design an idempotency-key flow that records the key and the effect atomically, and size its retention and storage
The lost acknowledgement
Loading question…
Some operations are already safe to repeat
Idempotent
- Set address to X
- Delete order 42
- PUT whole resource
Not idempotent
- Add $50
- Append a line
- Send an email
- Increment counter
Redesign
- Apply transfer T-9123 (unique ID)
- Record vote from U on P
Idempotency keys
Put the server's handling of a request carrying an idempotency key in order.
- 1Begin a database transaction
- 2Return the response
- 3Look up the key; if a completed result is stored, return it and stop
- 4Store the response under the key and commit the transaction
- 5Apply the business effect, such as the ledger entry
- 6Insert the key as in progress, relying on a unique constraint to stop a concurrent duplicate
The race that breaks naive dedup
t = 0
Copy 1: key not found
t = 5 ms
Copy 2: key not found
t = 6 ms
Copy 1 charges the card
t = 7 ms
Copy 2 charges the card
Fix
Unique constraint + effect in one transaction
How long to remember a key
Retention
>= retry window
Stripe keeps 24 h
Storage
rate x retention x entry
stored response dominates
Expiry
API contract
a correctness boundary
Loading question…
Consumers deduplicate too
Check your mastery, then lose an acknowledgement
Without dedup
duplicate effects
Atomic check-and-record + restart-safe
none
Score 80% or more. In the sandbox, build client, API, payment service, database. Add a short timeout and retry, plus a one-way partition that loses responses. Run, then add a dedup store with Atomic check-and-record and Survives a restart, and rerun the same seed.
Mastery check
4 questions on fresh variants. One attempt each, no time limit. Score 80% or more to master the lesson.
Answer this step to continue.