Definition
An idempotency key is a unique value a client sends with a request that creates something, so that sending the same request again has no additional effect. If a network error hides whether the first call succeeded, the client simply retries with the same key and the server returns the original result instead of creating a duplicate.
How it works
Retries are unavoidable: timeouts, dropped connections and restarted workers all leave a client unsure whether its request was processed. Without protection, a retry of 'create journal entry' books the sale twice, and the ledger is wrong until someone notices.
The fix is to derive the key from your own record, for example shop-order-1045 or the ID of the invoice in your billing system, and send it in the Idempotency-Key header. In Ledgeriano, a retried request with a key that was already used returns the existing entry with status 200 instead of 201 and records nothing new.
Do not generate a random key on each attempt: that defeats the purpose. Generate it once per business event and store it with the event, so every retry carries the same value.
Example: a retry after a timeout
A payment service sends POST /journal-entries with Idempotency-Key: payout-2026-11-05-001. The entry is created as number 482, but the response is lost in a timeout. The service retries with the same key and receives entry 482 with status 200. The ledger contains one entry, not two.