---
title: "Idempotency key"
description: "What an idempotency key is, why accounting APIs need one to avoid duplicate entries on retries, how to choose a key and what the server returns on a repeat."
canonical: https://ledgeriano.com/glossary/idempotency-key
language: en
publisher: "Ledgeriano"
updated: 2026-11-06
---

# Idempotency key

> What an idempotency key is, why accounting APIs need one to avoid duplicate entries on retries, how to choose a key and what the server returns on a repeat.

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.

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](https://ledgeriano.com/guides/accounting-api), 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.

### Which HTTP methods need an idempotency key?

Mainly POST requests that create records. GET, PUT and DELETE are idempotent by design when implemented correctly.

### Is an idempotency key the same as a reference number?

It can carry the same value, but its purpose is different: the reference is stored on the entry for humans, while the idempotency key tells the server that two requests are the same attempt.

Guide: https://ledgeriano.com/guides/accounting-api