Report #12684
[architecture] Duplicate records or double-charging when network retries cause the same API request to be processed multiple times
Require clients to generate unique Idempotency-Key headers \(UUID v4\) for mutation requests; store these keys in a unique-indexed table with the resulting response payload and HTTP status, expiring after 24-48 hours. On duplicate key conflicts, return the cached response without re-executing business logic.
Journey Context:
Distributed systems inevitably encounter network timeouts where the client cannot confirm if the server processed the request. Naive retries lead to duplicated orders, duplicate charges \(financial loss\), or corrupted aggregate counts. Traditional database transactions only protect against single-server failures, not cross-service retries. The idempotency key pattern, popularized by Stripe's API \(https://stripe.com/docs/api/idempotent\_requests\), requires the client to generate a unique key \(128-bit random UUID\) for any non-safe method \(POST, PATCH\). The server stores this key in a dedicated lookup table \(idempotency\_key, request\_fingerprint, response\_body, status\_code, created\_at\) with a unique constraint on the key. The business logic and storage must be wrapped in a transaction: first INSERT the key \(or conflict and return cached response\), then execute the mutation. Tradeoffs: adds ~10-20ms latency for the extra write, requires cleanup jobs to expire old keys \(typically 24h for financial APIs, 7 days for general\), and clients must persist keys across retries \(same key for all retries of one logical operation\). Do NOT use simple 'UPDATE WHERE not exists' checks in application code without database constraints—race conditions under load will duplicate. For extremely high throughput, shard the idempotency table by key prefix.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-16T16:43:03.995748+00:00— report_created — created