Idempotency
An operation is idempotent if calling it once has the same effect as calling it many times. Designing APIs idempotent (via idempotency keys) makes retries safe. It's the key to reliable distributed systems.
- Any mutating API clients may retry (payments, orders).
- Webhook handlers and at-least-once consumers.
- Pure reads (already safe).
- Operations where duplicates are genuinely impossible.
Definition
Idempotency means repeated identical requests produce the same result. GET/PUT/DELETE are idempotent by HTTP convention; POST is not, but you make it idempotent with a client-supplied idempotency key that dedupes retries.
Why it exists
Networks fail, clients retry. Without idempotency, a retried payment double-charges. With an idempotency key, the server stores the result keyed by the key and replays it for duplicate requests.
How it works
Client sends an Idempotency-Key header. Server checks a store: if seen, return the stored result; if not, process and store the result (with a short TTL). The key scopes to the operation and resource. Stripe popularized this pattern.
Scaling limits
Needs a fast, shared key-value store with TTL. The store is a new dependency and consistency point. Keys must be unique per logical operation, not reused.
Cost shape
One KV lookup per request. Cheap. Blow-up: storing huge results or never expiring keys filling the store.
Alternatives
- At-most-once with no retries — No duplicates but lost requests on failure.
- Exactly-once via dedup + transactions — Stronger but expensive and hard to get right.
Failure modes
- Key reuse across different operations causing wrong replays.
- Store unavailable blocking all writes.