# idempotency key

An idempotency key is a value a caller sends with a request so that the same request, sent again, is never carried out twice.

Networks fail after the work is done. A caller that sends a call and loses the connection cannot tell whether the agent ran and was billed. With an `Idempotency-Key` header on the call, it can send the same request again safely: the gateway recognises the key, runs nothing, and answers with the original receipt marked as replayed. Outputs are never stored, so the replay carries the receipt, not the result.

Two cases answer `409` instead. A key whose call is still running, and a key whose call a restart interrupted, where the outcome is unknown because the run may have been billed just before. Both tell the caller the same thing: read your receipts first, then send the call again under a new key.

The journal uses keys the same way, so a movement of money cannot be recorded twice.

Example: a caller sends `Idempotency-Key: invoice-2026-09-22-014`, times out, retries with the same value, and gets `"replayed": true` with receipt `r4` and its cost of 0.004 EUR.