Problem
Network failures cause retries. Without idempotency, retries create duplicate charges, orders, emails. Need exactly-once semantics.
data-consistencyestablished · low operational burden
Idempotency Patterns
Also known as: idempotency-key, exactly-once, deduplication, idempotent-receiver
Intent
Make operations safely retryable using idempotency keys, natural idempotency, and idempotent receivers — preventing duplicate side effects.
Forces
- •Clients cannot distinguish 'failed' from 'timeout'
- •Retries are mandatory for reliability
- •Duplicate side effects: double charge, duplicate order, duplicate email
- •Exactly-once delivery impossible; exactly-once processing achievable
Solution
✓ When to Use
- •Any POST/PATCH/DELETE exposed to retries
- •Webhook endpoints (at-least-once delivery)
- •Payment, order, reservation systems
✗ When Not to Use
- •GET (naturally idempotent)
- •High-throughput internal RPCs (exactly-once infra)
- •Operations where duplicates harmless
Pros
- +Simple client contract: add header
- +Works over any transport (HTTP, gRPC, MQ)
- +No distributed coordination needed
Cons
- −Storage overhead (mitigate: TTL, cleanup)
- −Client must generate/persist keys
- −Doesn't solve server crash mid-processing (needs outbox)
Cost Profile
Infrastructure
Low — key-value store with TTL
Operational
Low — standard monitoring
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
Partial failure: DB commits, event publish fails (needs outbox)
Real-World Examples
Alternatives
- outbox-pattern
- exactly-once-delivery
- natural-idempotency
- deduplication
Related Patterns
- outbox-pattern
- idempotency-key
- exactly-once-illusion
- deduplication
- retry-with-backoff
Competency Domains
data consistencydata statereliability opsdistribution communicationeconomics evolution