api-designcorrectnessretriespayments
Idempotency Keys
Guarantee repeated client retries do not create duplicate side effects.
Definition
An idempotency key uniquely identifies a client operation so duplicate requests can return the original result.
When To Use
- Payment, booking, and order creation APIs exposed to retrying clients.
- At-least-once delivery pipelines where duplicates are expected.
- Any mutation endpoint crossing unreliable network boundaries.
When Not To Use
- Pure read endpoints or fully deterministic stateless GET flows.
- Internal fire-and-forget operations without replay safety requirements.
- Extremely high-cardinality low-value writes where storage overhead is unjustified.
Tradeoffs
- Prevents duplicate side effects, but requires dedup store lifecycle management.
- Improves API correctness, but adds write amplification on key checks.
- Supports safe retries, with complexity around key expiration windows.
Common Failure Modes
- Dedup window too short allows duplicate replays.
- Key scope mismatch blocks legitimate repeated operations.
- Inconsistent dedup store replication causes cross-region duplication.
Interview Framing
Use this structure when the interviewer asks for this pattern explicitly.
Define key scope, retention TTL, conflict response semantics, and how dedup interacts with async workflows.
Related Project Deep Dives
Event Deduplication Platform for Idempotent Processing
Design a platform that removes duplicate events across distributed pipelines with low latency.
Global E-Commerce & Payment Platform
Design a globally distributed commerce system with catalog, cart, inventory reservations, checkout orchestration, multi-PSP payments, fulfillment, and financial ledger correctness.
Related Concepts
Exactly-Once Processing (Practical)
Achieve effective exactly-once outcomes via idempotency, transactions, and dedup rather than magic guarantees.
Transactional Outbox Pattern
Atomically persist business state and event records in one DB transaction, then publish asynchronously.
Saga Pattern
Coordinate multi-service workflows with local transactions and compensating actions.