Skip to content
Fakturnaut
Sign up free

Idempotency: retry without issuing twice

Issuing an invoice and delivering it must happen exactly once, even if your connection drops. Send an Idempotency-Key header (1 to 200 visible ASCII characters, e.g. a UUID or your order number) with POST /invoices and POST /invoices/{id}/deliveries.

  • Same key, same body: you get the original result (200, header Idempotent-Replayed: true). Nothing is issued or sent again.
  • Same key, different body: 422 idempotency.key-reused. Use a new key for a new invoice.
  • Same key at the same time: one request wins, the other gets 409 idempotency.conflict; retry it.

Keys are kept for 30 days. Live and test keys have separate key spaces.

Retry rules

Retry with the same key after a timeout, a network error, 429 or 503 (wait for Retry-After). Do not retry 4xx errors other than 408, 409 idempotency.conflict and 429: fix the request instead.

Any random UUID works as a key; the SDKs will have a helper for it once they are published. Invoice numbers are unique per seller too: issuing a number twice answers 409 invoice.duplicate-number.