DEV Community

Alex Georghiou
Alex Georghiou

Posted on

Idempotency Keys Are Business Logic

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
Enter fullscreen mode Exit fullscreen mode

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)