idempotency-patterns

Idempotency Patterns

Purpose

Provide standardized recipes for the three pieces of API plumbing that clients depend on and servers get subtly wrong: safe retries (idempotency keys so a retried mutation applies once), pagination (stable, bounded traversal of collections), and rate limiting (standard headers so clients back off correctly). All three are static, framework-agnostic patterns, apply them at the boundary, in the handler.

Why idempotency

HTTP defines GET, HEAD, PUT, and DELETE as idempotent (repeating them has the same effect as doing them once) and GET/HEAD as safe (no side effects). POST is neither: and networks retry. A client that times out and retries a POST /payments can charge twice. The fix is an idempotency key: the client sends a unique Idempotency-Key header; the server records key → outcome and, on replay, returns the stored outcome instead of re-executing.

The idempotency-key algorithm (unsafe methods only)

1. Read the Idempotency-Key header. If absent on a create endpoint, either require it (400) or proceed without dedup, decide per endpoint.
2. Look up the key (scoped to the authenticated principal + endpoint) in a durable store.
3. Hit, completed → return the stored status + body verbatim. Do not re-run.
4. Hit, in-flight → the original is still processing: return 409 (or block briefly), never run concurrently.
5. Miss → atomically insert the key in an in-flight state (unique constraint / SET NX), execute the work, store the response, mark completed, set a TTL.
6. Guard against key reuse with a different body: store a hash of the request; if the same key arrives with a different payload, return 422.

Apply idempotency only to unsafe, non-idempotent methods (POST, and non-idempotent PATCH). GET/HEAD/PUT/DELETE are already idempotent by contract, do not bolt a key onto them. Full store recipes and TTL/window guidance are in references/idempotency-recipes.md.