The Idempotency Key
Retries that can never double-charge, double-create, or double-anything.
The incident
The user clicked Pay. The charge succeeded. The success response died somewhere on a mobile network. The app, seeing a timeout, said 'something went wrong — try again.' The user tried again. Two charges, one order, and a support ticket that turned into a chargeback.
Why the obvious approach fails
Distributed systems have a truth that intuition resists: a timeout is not a failure. It's an unknown. The request may have failed, succeeded, or be executing right now. Any client that retries on timeout — which is every client, because networks are unreliable — will eventually re-execute an operation that already succeeded. You cannot solve this on the client, because the client is the party that doesn't know. The server has to be able to recognize a retry and answer it without re-executing.
The standard
- Every state-changing request on a critical path (payments, orders, account mutations) carries a client-generated Idempotency-Key header — required, not optional.
- The server stores the result of the first execution keyed by that key; replays return the stored response without executing.
- Key storage has a declared retention window matched to the client retry horizon.
- Retries and originals are distinguishable in logs — replay rates are a monitored signal of network health.
- The retry layer (Retry Helix) and this module are always deployed together; backoff without idempotency is still dangerous.
How Cortex validates it
At plan time
The blueprint marks every financially- or state-critical mutation; each must declare idempotency handling before build.
At validation
assert: critical_mutations.require(Idempotency-Key)assert: replay(key) → cached_response && side_effects == 0Assertion syntax is illustrative.
At review
The approver sees the replay test: same key sent twice under simulated timeout, one charge, identical responses.