Technical Article
An Idempotency-Key is an execution protocol, not just a database constraint.
A client experiences a network timeout, but the payment was already processed by the upstream provider. When the client retries the POST request with the same Idempotency-Key, the API must decide whether to return the previous result, wait, or safely attempt execution again.
A database UNIQUE constraint prevents two rows from sharing the same key, but it cannot answer the most critical operational question: what should the system do when a retry arrives while the initial request is still executing an external side effect?
An Idempotency-Key must therefore represent an observable execution protocol: uniquely identifying the operation, atomically claiming execution ownership, tracking lifecycle progress, and defining exactly what the client receives on each repetition.
The idempotency record should bind the tenant, operation, key, and a cryptographic fingerprint of the payload, transitioning through explicit states such as in_progress, completed, and recoverable. This prevents the same key from being reused as authorization to execute divergent commands.
If the operation has already completed, the server returns the stored status code and response payload. If execution is still in progress, the API can return an explicit 409 Conflict or coordinate waiting, provided this behavior is an explicit part of the HTTP contract.
When a key reappears with a different payload, the server must reject the attempt—for example, with 422 Unprocessable Content. Silently accepting altered parameters transforms a retry-safety mechanism into an unpredictable source of ambiguity.
The hardest failure boundary occurs when the external operation succeeds at the provider and the local worker crashes before recording success, leaving an intermediate state that no database constraint can resolve on its own.
In this scenario, recovery depends on idempotency support in the destination service or automated reconciliation with an authoritative source, paired with explicit expiration policies, error retention, and failure-recovery mechanisms.
The goal extends beyond preventing duplicate database records: it enables clients to safely retry business intentions across network failures while the server preserves operational identity and deterministically explains what occurred.