01
Install
The CLI ships the same client the SDKs wrap. Node 18+ or any runtime with fetch.
npm i @ledgerdoc/clientIdempotent postings
How Ledgerdoc guarantees that a retried write posts exactly once, even when the network disagrees about whether the first attempt arrived.
Every write endpoint accepts an Idempotency-Key header. The key is an arbitrary string you choose, scoped to your workspace, and retained for 24 hours. If two requests arrive carrying the same key, the second returns the original response — it does not create a second entry.
Why retries are unavoidable
A client that times out cannot tell the difference between a request that never arrived and a response that was lost on the way back. Retrying is the only safe behaviour, so the ledger has to make retrying safe.
Rule
Generate the key from something stable in your own domain — an invoice ID, a payout batch, a settlement reference. Never generate it per attempt, or every retry becomes a new posting.
Replay behaviour
The response to a replayed request carries a Replayed: true header so you can distinguish it in logs. The body is byte-identical to the first response, including the original posted_at timestamp.
Replay — second attempt
# Same Idempotency-Key, sent twice.
HTTP/1.1 201 Created
Replayed: true
Content-Type: application/json
{
"id": "ent_8Fq2wZ",
"balanced": true,
"posted_at": "2026-07-14T09:12:44Z"
}Key conflicts
Reusing a key with a different payload is an error, not a silent overwrite. The ledger returns 409 idempotency_conflict and writes nothing.
| Condition | Status | Result |
|---|---|---|
| Same key, same payload | 201 | Original response replayed, no new entry |
| Same key, changed payload | 409 | Rejected as idempotency_conflict |
| Same key, after 24h | 201 | Treated as new — key has expired |
| No key supplied | 201 | Posted, but retries are unsafe |
Scope and retention
Keys are scoped per workspace and per environment. A sandbox key and a live key never collide. Retention is 24 hours from first use; after that the key is forgotten and a request carrying it is treated as new.
- Keys are case-sensitive and capped at 255 characters.
- Replays do not count against your write rate limit.
- Reads are naturally idempotent and ignore the header.