Problem
Network failures cause clients to retry requests. Without idempotency, retries create duplicate side effects: double charges, duplicate orders, corrupted state.
messagingestablished · low operational burden
Idempotency Key
Also known as: deduplication token, idempotency token
Intent
Make any operation safely retryable by attaching a unique client-generated key that the server uses to detect and ignore duplicates.
Forces
- •Clients cannot distinguish 'request failed' from 'response lost'
- •Servers must process retries without creating duplicate effects
- •Idempotency state must survive server restarts
- •Key space must be large enough to avoid collisions
Solution
✓ When to Use
- •Any write operation exposed to retries (payments, orders, reservations)
- •Webhook endpoints receiving at-least-once delivery
- •API endpoints where clients implement retry logic
✗ When Not to Use
- •Read-only operations (GET is naturally idempotent)
- •Operations where duplicates are harmless or desired
- •High-throughput internal RPCs where exactly-once infrastructure exists
Pros
- +Simple client contract — just add a header
- +Works over any transport (HTTP, gRPC, message queues)
- +No distributed coordination required
Cons
- −Storage overhead for key registry (mitigate with TTL + cleanup)
- −Client must generate and persist keys across retries
- −Doesn't solve server-side crashes mid-processing (needs outbox)
Cost Profile
Infrastructure
Low — key-value store with TTL
Operational
Low — standard monitoring on key store
Cognitive
Low — well-understood pattern
Failure Modes
Key store unavailable → false duplicate rejection or missed deduplication
Key collision (extremely rare with UUID v4)
Client reuses key for different operation → silent corruption
Real-World Examples
Alternatives
- outbox-pattern
- exactly-once-delivery
Related Patterns
- outbox-pattern
- transactional-outbox
- duplicate-detection
Competency Domains
data statereliability ops