Why does every mutating API need an idempotency key?

Category: System Design

Answer

Without a key, a network retry can charge the customer twice. With a key, the server stores {key -> response} for, say, 24h and replays the stored response on the second request. Stripe’s pattern is the canonical example. Pair with a write-once guard.

Concrete examples from the fca project context

Example 1

Client sends Idempotency-Key: <uuid> in POST /refunds.

Example 2

Server stores (key, response_body, status, ts) for 24h; same key returns the stored response.

Example 3

In-flight dedupe: a SECOND concurrent request with the same key waits for the first to finish.

Example 4

Keys never reused; expired keys are deletable.

Data flow / flow chart

POST + Idempotency-Key
  -> server stores (key, response) for 24h
  -> retry returns stored response

Takeaway

Idempotency keys are the cheapest insurance against double-charges.