Idempotency Keys Are a Contract, Not a Header

Clients retry. Networks drop responses after the server committed. Without idempotency, a retried payment becomes two payments.

The mechanics

The client generates a unique key per logical operation and sends it with every retry. The server:

1. Looks up the key in a durable store.
2. If absent, records in_progress, executes, stores the response, returns it.
3. If present and complete, returns the stored response.
4. If present and in progress, returns 409 or waits.

The key must be scoped to the authenticated principal, and the stored response should include the status code and body, not just "done".

The hard parts

• Atomicity: writing the key and the business effect must be in the same transaction, or the key write must happen before the effect with recovery on crash.
• Retention: keys older than the retry window can be purged, but purge too early and a late retry duplicates.
• Request fingerprinting: reject reuse of a key with a different payload.

Takeaway: idempotency is a stored state machine. If the key and the effect are not atomic, you have renamed the duplicate, not removed it.