Make repeated calls to a non-idempotent endpoint safe.

Data Flow

POST /payments
Idempotency-Key: 7f3a-4c21-9b58  (client-generated UUID)

first call:   record (key, request, status=in_flight)
              process payment
              update (key, status=200, response)
retry:        find (key); if status=200 -> return cached response
              if status=in_flight -> 409 conflict

When to use

• Any non-idempotent write reachable over an unreliable network.
• Payments, ledger entries, emails, side-effect-trigger APIs.

Pitfalls

• Key collision across different operations. Scope the key (user_id + endpoint + purpose).
• TTL on cached responses too short: a late retry may re-execute the side effect.
• Not returning the same response body on retry — clients see “different” answers for the same key.

Analogy

A receipt stapled to a request: “if you ever see this request again, just give me the answer I already paid for”.

Interview tip: Stripe’s idempotency design is the gold standard. Quote it.