Idempotency
One header that makes retrying a send safe.
Send an Idempotency-Key header on any POST that creates something. Repeating a key with the exact
same request returns the original result instead of acting twice — safe for retrying a request whose
response you never saw. Keys are scoped to your organisation and, as implemented today, are not
expired or cleaned up — reusing a key from weeks ago behaves the same as reusing one from a minute
ago. Generate keys that are unique per logical send (an order/invoice reference is fine); don't reuse
one on purpose expecting it to have "worn off."
Two cases beyond a clean replay:
- Same key, different request body. The key is bound to a fingerprint of the request the first time
it's used. Reusing it for a body that hashes differently is a caller bug, not a replay — you get a
409 CONFLICT_ERROR, not the earlier response. - Same key, first attempt still in flight. If a retry arrives while the original request is still
being processed, you get a
409 CONFLICT_ERRORtelling you to retry shortly, rather than a second attempt racing the first.
Use it on every send
An invoice number, once issued, is permanently claimed by that taxpayer. A retried send without an
idempotency key either duplicates the invoice or fails with a 409 CONFLICT_ERROR on the
duplicate VAT-scoped invoice number — and neither is cleanly recoverable after the fact.