Basics
Idempotency
Retry any request without creating anything twice.
A network error does not tell you whether your request arrived. Every operation that creates something can be retried safely:
| Operation | What makes it safe |
|---|---|
PUT …/by-ref/… | it is an upsert: the same request twice is one record |
POST /invoices | the Idempotency-Key header, below |
POST /invoices/{id}/send | an invoice that went out is not mailed again; the answer is the invoice as it is |
POST /invoices/{id}/cancel | an invoice that is cancelled already answers 200 with its cancellation invoice |
POST /contracts/by-ref/…/usage | each record's external_ref is stored once; the answer counts recorded and duplicates |
POST /revenue-events | (source, external_ref) is stored once; a repeat answers 200 with the first event |
Idempotency-Key
POST /invoices requires the header — 1 to 255 printable ASCII characters without spaces, a UUID for example:
Idempotency-Key: 8e0b3c5e-2f7a-4f6e-9a51-0c2d6f0e1a77- Same key, same body:
200with exactly the first answer, stored, not computed again, and the headerIdempotent-Replayed: true. Nothing is created, issued or mailed.GETgives you the current state. - Same key, different body:
409 idempotency_key_reused. "Same" means the same body after validation, in canonical form: the order of fields does not matter, but"1"and"1.0"as a quantity are different. - A failed request does not use up its key. Fix the cause — an admin completes the company's tax number, say — and send the same request with the same key.
- At the same time: of two requests with the same key, the second waits for the first and returns its answer.
Of two keys for the same
external_ref, one creates the invoice and the other gets409 invoice_external_ref_exists.
Keys are per company, whichever API key sends them, and are never deleted.
When to retry
Retry with the same key after a network error, a 5xx, or 409 conflict_retry (two requests met at the same
moment). Wait a little longer each time. Do not retry other 4xx answers unchanged — they say what to fix.