Idempotency

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.

How to use it

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": [ ... ] }'

What happens on a retry

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.

Reusing a key with different parameters is an error

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.

Concurrent requests

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.

Details

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: true

A 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.