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 again | 200 OK with the original data; nothing is posted twice |
| Same key while the first request is still running | 409, meta.error_code: "idempotency_key_in_use", retry after meta.retry_after_seconds |
| Key already used by a different operation (e.g. a reversal) | 409, meta.error_code: "idempotency_key_reused" |
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.