Ledga

Idempotency

Every posting carries a client-chosen key; a retry returns the original result.

idempotency_key is required on POST /transactions and on each item of POST /transactions/batch; it is optional on reversals. String endpoints accept it as the Idempotency-Key header or an idempotency_key body field.

Situation Response
First use 202 Accepted (transactions) or 201 Created (strings)
Same key and body again 200 OK with the original data; nothing is posted twice. For a transaction, meta.replayed: true, and status stays pending
Same key while the first request is still running 409, meta.error_code: "idempotency_key_in_use" or "idempotency_lock_failed", retry after meta.retry_after_seconds
A transaction’s key with a different body, or a key already used by a different operation (e.g. a reversal) 409, meta.error_code: "idempotency_key_reused"

A transaction’s verification state is read from GET /transactions/{id}/status. A batch item follows the same rules: a replay is accepted with the original id; a refusal is rejected with the error_code.

Keys are scoped to the ledger. Derive them from your own record (invoice-1042-payment) rather than generating a random value you could lose before the retry.