idempotency-keyslisted

# Idempotency keys A retry after a network timeout must not charge the card twice. The client names the operation with a key; the server ensures one execution and replays one recorded response. ## Method 1. **Client generates, server scopes.** Client sends `Idempotency-Key: <uuid>` per logical operation (same key on retry, new key for a genuinely new attempt). Server scopes stored keys by authenticated caller and endpoint so keys cannot collide across tenants or routes. 2. **Reserve the key atomically before doing work.** Insert `(key, scope, request_hash, status=in_progress)` with a unique constraint in the same database as your business data. Lost race = key exists: this is the whole mechanism; check-then-insert without the constraint is a duplicate generator under load. 3. **Bind the key to the request body.** Store a hash of the payload; same key + different hash returns 422. Otherwise a client bug replays order A's response to order B's request. 4. **Record the outcome, replay it verbatim.** On completion, store status code and response body against the key; any later duplicate gets exactly that response with an `Idempotent-Replay: true` header. Concurrent duplicate while in_progress: 409 with Retry-After, do not run the work twice in parallel. 5. **Choose the failure policy explicitly.** Recommended: store the error response for deterministic failures (validation) but clear the key on infrastructure failures so a retry