API errors

Invalid Idempotency-Key header

The Idempotency-Key header was present but not usable — it exceeds the maximum length of 255 characters. The request was not processed.

Error type

https://normbill.com/docs/errors/idempotency-key-invalid

HTTP status

400

Common causes

• A key longer than 255 characters was sent.
• A structured payload (e.g. serialized JSON) was used as the key instead of an opaque identifier.

How to fix it

• Use an opaque identifier of at most 255 characters — a UUID per distinct invoice is ideal.
• Omit the header entirely if you do not need retry safety; it is optional.

The error response format

Every non-2xx response from the API is an RFC 9457 problem-details body (application/problem+json) with at least type, title, status and detail. The type URL links back to this reference.

All error slugs: invalid-request, bad-request, payload-too-large, unauthorized, validation-failed, unparseable-document, plan-limit, quota-exceeded, rate-limited, overage-cap-reached, validate-fair-use, idempotency-key-invalid, idempotency-key-reuse, idempotency-conflict, pdf-unavailable, validator-unavailable, not-ready. Still stuck? Email support@normbill.com or start at the docs overview.