Back to roadmap
Module 5 · APIs & Application LayerDay 04425 min

Idempotency and Retries

Retries are inevitable; design as if every call may run twice.

Day 044

Idempotency and Retries

Client
client
API
service
KV (key→resp)
datastore
Charge proc
external
Signal path
Idempotency key handshake
Client
client
Idempotency-Key
API
service
API
service
flow
KV (key→resp)
datastore
API
service
flow
Charge proc
external
Memory hook

Idempotency and Retries: retries are inevitable

Mental model

turn boundaries into contracts

Design lens

Keys must be globally unique per operation.

Recall anchors
MechanismRetries

Why it matters

Idempotency means doing the same operation N times has the same effect as doing it once. For safe verbs (GET) it's natural; for POST/charge/send-email, it's a deliberate design choice with idempotency keys.

Deep dive

Server stores key → result for a TTL; replay returns the same response.

Retries: jittered exponential backoff to avoid thundering herd.

Combine with at-least-once delivery from queues — every consumer must be idempotent.

Demo / scenario

Charge endpoint must not double-bill.

  1. Client sends 'Idempotency-Key: <uuid>'.
  2. Server stores key with response.
  3. Client retries on timeout; server replays response.
  4. TTL on key is hours/days; cleanup is async.

Tradeoffs

  • Keys must be globally unique per operation.
  • Client must reuse the same key per logical attempt.
  • Storage cost is real — TTL aggressively.

Diagram

Idempotency-Key
Client
API
KV (key→resp)
Charge proc
Idempotency key handshake.

Mind map

Check yourself

Loading quiz…

Sources & further reading