Idempotency Keys Are Business Logic
An idempotency key is often described as an HTTP convenience. In payment, provisioning, and order systems, it is part of the business contract.
A caller sends a request, waits, and times out. The server might have completed the operation. If the caller retries without a stable identity for the intended action, the server may perform it twice.
A robust design associates the idempotency key with the caller, the operation type, and a normalized request fingerprint. A repeated request returns the original outcome or a clear in-progress status. A repeated key with a different payload is a conflict, not a new instruction.
The tricky part is concurrency. Two requests with the same key can arrive at nearly the same time. A check-then-insert sequence is not enough; you need a uniqueness constraint or equivalent atomic ownership mechanism. Expiration policy matters too, because old keys cannot remain forever in every system.
Request + key
|
v
Atomic claim
|-- first use --> execute --> store result
|-- duplicate --> return stored result
|-- mismatch --> reject
Do not promise that every internal action is magically exactly once. Promise a clearly defined externally observable behavior, then design storage and downstream interactions around that promise.
Top comments (0)