idempotency-key-designlisted

# Idempotency-Key Design ## When to Use This Skill Any `POST` or `PATCH` that has a side effect the caller must not repeat: charge a card, create an order, send a notification, initiate a transfer. If the client retries on a network timeout, the operation must not execute twice. ## 1. The Contract ``` POST /orders Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000 Content-Type: application/json { "items": [...], "total": 99.95 } ``` - The header name is `Idempotency-Key` (title-case, per the IETF draft — `[verify-at-build]` on draft status). - Value: a **client-generated** UUID v4 (or ULID). The server treats it as opaque. - The server stores the key + response for the dedup window; re-submitting the same key returns the stored response without re-executing. ## 2. Server-Side Design Checklist | Step | Detail | |---|---| | Parse and validate | If header absent on a non-idempotent-by-design endpoint → 422 or proceed without dedup (document which). If header present but malformed → 400. | | Lock the key | Atomically: check-and-set the key in a store (Redis SETNX, DB upsert). If key already locked and processing → 409 `in-progress`. | | Execute or replay | Key absent → execute normally, store `(key, status, response_body, expires_at)`. Key present + complete → return stored response with original status. | | Dedup window | Minimum 24 hours, typically 7 days. Beyond the window, treat as a new request. Document the TTL. | | Scope | Key is scoped to the **authenticated ca