Network hiccup during payment: did the charge go through? Retry might double-charge. Idempotency keys let clients retry safely.

Clientgenerates keyAPI endpointCheck idempotencykey in cache?Cache hitreturn cachedCache missexecute actionStore resultcache with keyReturn responseRedisidempotency storeActual DBcharge, insertTTL cleanup24h retention
Idempotency key: check cache → return cached OR execute + cache
Advertisement

Client generates key

UUID per logical operation. Retries use same key. Server can dedupe.

Client generates key

UUID per logical operation. Retries use same key. Server can dedupe.

Advertisement

Server checks cache

Key in Redis? Return cached response. Same status, same body. Client can't tell it's a retry.

Cache miss → execute

Real action runs. Charge card. Insert order. Whatever.

Store the response

Full response cached against key. TTL 24h typical. Retries within TTL get same response.

What can go wrong

Concurrent requests with same key. Lock during execution. Second request waits, gets result of first.

Key + cache lookup + lock during exec + cache result + TTL. Safe retries everywhere.