Glossary / idempotency key
Definition

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.

See also: receipt, journal entry, gateway, settlement.

Used in: Audit what your agents spend.