Architectural Breakdown & AnalysisFAANG Aligned
Network retries can cause clients to submit payment requests multiple times. Idempotency guarantees that executing an operation multiple times yields the exact same result as executing it once.
Step-by-Step Implementation
- Client Generation: Client generates a unique UUID
Idempotency-Keyheader for the transaction request. - Gateway Lock Check: API Gateway attempts to acquire a Redis lock for
idempotency_key. - If key exists and status is
PROCESSING, return HTTP409 Conflictor wait. - If key exists and status is
COMPLETED, return the cached payment response payload immediately. - Execute & Store: Process payment, record transaction in DB, save response payload in Redis with 24h TTL, and release lock.
NOTE — Stripe API Standard
Stripe handles millions of payment retries safely using client-supplied Idempotency-Key HTTP headers.
Key Architectural Comparison
| Idempotency Implementation | Storage Tier | Collision Behavior | Production Standard |
|---|---|---|---|
| DB Unique Constraint | Primary Relational DB (idempotency_key). | Returns SQL duplicate key violation (23505). | Mission-critical financial ledgers. |
| Redis Distributed Lock + Key | Redis Cluster (SET key val NX EX 120). | Returns HTTP 409 Conflict immediately. | High-throughput payment gateways (Stripe). |