Retry any mutating request safely. Send an Idempotency-Key and a repeat of the same call returns the original response instead of doing the work twice.
Generate a unique key per logical operation — a UUID v4 is ideal — and send it on every POST, PUT, PATCH and DELETE. Reuse the same key when you retry that operation, and only then.
curl -X POST https://api.brivio.ro/v1/invoices \
-H "Authorization: Bearer brivio_sk_live_..." \
-H "Idempotency-Key: 5f9c3b2a-1d4e-4a7b-9c8d-0e1f2a3b4c5d" \
-H "Content-Type: application/json" \
-d '{ "contact_id": "...", "lines": [ ... ] }'The first request executes and its status code, response body and relevant headers are stored. A retry within 24 hours returns that stored response verbatim, with Idempotent-Replayed: true so you can distinguish a replay from a fresh execution. The work is not performed again.
If the same key arrives with a different request body, Brivio returns 409 IDEMPOTENCY_KEY_REUSED rather than replaying the old response.
This is deliberate, and it is the part most implementations skip. Silently replaying would tell you your new request succeeded when nothing ran — you would believe a second invoice exists when it does not. An error surfaces the bug (usually a hard-coded key, or a retry loop that mutates the body between attempts) at the moment it happens.
Key ordering in JSON does not matter; the fingerprint is computed over a canonical form, so re-serialising an identical body is still a valid retry.
If two requests carrying the same key arrive at once, exactly one executes. The other receives 409 IDEMPOTENCY_IN_PROGRESS — retry after a short delay to collect the stored response. Requests are serialised in the database, so this holds across processes and regions, not just within one server.
Header Idempotency-Key
Max length 200 characters (longer keys are truncated)
Retention 24 hours from first use
Scope per organization + endpoint — your keys never collide with
another tenant's, and the same key on two different endpoints
is two independent operations
Methods POST, PUT, PATCH, DELETE (GET needs no key)
Replay marker Idempotent-Replayed: trueA request that failed is not replayed: retrying with the same key after a 5xx gets another attempt at the work, which is what you want. Only completed responses are stored for replay.
Omitting the header is allowed and simply disables all of the above for that call. For anything that creates a document, moves money or submits to ANAF, send a key.