Idempotency

Consider a request that creates a transaction. It reaches Ledgr, the transaction is written, and then the connection drops before the response gets back to you. You do not know whether it worked. Retrying might move the money a second time; not retrying might leave it unmoved. Idempotency removes that dilemma.

Send a unique value in the idempotency_key header on any request that changes state:

idempotency_key: pay_9f2a1c

Ledgr processes the first request with a given key and remembers its result. If a request arrives later with the same key, Ledgr returns the original result instead of doing the work again. A retry after a timeout is therefore always safe: at most one transaction is created, no matter how many times you send it.

Using keys well

• One key per operation. Derive it from something stable in your own system, such as an order id (order_8412_capture), or generate a fresh UUID and store it with the operation.
• Reuse a key only to retry the same operation. A new operation should always use a new key.
• Keys are scoped to your account, so they never collide with another integration's.
• Idempotency covers writes: creating transactions, funding accounts, placing and capturing holds, and the like. Reads change nothing, so they never need a key.