Documentation Index
Fetch the complete documentation index at: https://preflight-ee1e633f.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
Networks drop packets, clients retry, and queues redeliver. Without idempotency, the same user intent can create duplicate charges, tickets, or posts. Idempotency keys make “exactly-once behavior” practical on “at-least-once” infrastructure.
Why it matters
Retries can duplicate side effects without idempotent design. Payment and ticketing integrations are the usual victims—duplicate idempotency keys should return the original result, not create a second record.
Scope
Decide whether keys are global, per-tenant, or per-user. Collisions across tenants are rare but catastrophic if namespaces overlap.
Keys
Supply a stable idempotency key derived from natural identifiers—order ID, request UUID, or hash of canonical fields. Avoid keys that change when unrelated whitespace changes.
Rotation
If you must rotate key material, dual-write during transition and document the overlap window.
Storage
Record processed keys long enough to cover your retry window plus clock skew. Expire old keys to bound storage, but not before your longest plausible retry storm.
Conflicts
When a new payload arrives with an existing key but different body, reject loudly—something is inconsistent and needs human review.
