Distributed systems · intermediate
Idempotency
An operation is idempotent when making the same intended request multiple times has the same intended effect on server state as making it once, even though individual responses may differ.
Why it matters
Clients often cannot tell whether a timed-out request took effect, so idempotency makes retries safe from duplicate state changes such as repeated charges or orders.
Mental model
How to reason about idempotency
Separate invocation count from resulting state. A set-to operation converges on one state; an append operation accumulates unless a request identity lets the server recognize repeats.
Analogy
Pressing an elevator's lit call button again keeps one request active, while inserting another vending-machine coin creates another purchase credit.
Examples
See the boundary, not just the happy path
Worked example · Replace a resource state
PUT /users/42 with the same complete representationRepeated identical requests intend the same resource state, so PUT is defined as idempotent even if logging or response details vary.
Worked example · Deduplicate a create
POST /charges with Idempotency-Key: request-7The server can bind the key and request scope to the first result and return it for a safe retry instead of creating another charge.
Useful contrast · Safe versus idempotent
DELETE changes state but repeated DELETE has the same intended effectSafety means the method is read-only in intent; idempotency permits mutation as long as repetition does not add another intended effect.
Common mistakes
Misconceptions to remove early
Requiring identical responses
A first DELETE may return success and a later one not-found. Idempotency concerns the intended server effect, not byte-for-byte response equality.
Accepting a key without defining its scope
Key ownership, request fingerprint, retention period, and concurrent duplicate handling must be specified or unrelated operations can collide or duplicate.
Quick check
Can you predict the result?
1. Which statement best describes an idempotent request?
- • Repeating it has the same intended server effect as performing it once
- • It can never modify server state
- • It must return the identical status and body every time
2. What must an idempotency-key implementation define beyond accepting the header?
Keep building