idempotency-patternslisted

# 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 (uni