API errors

Validation fair-use allowance exhausted

Validation calls are free and never billed, but they are protected by a fair-use allowance of five times your plan's monthly document quota. That allowance is used up for the current period; your billable document quota is unaffected.

Error type

https://normbill.com/docs/errors/validate-fair-use

HTTP status

429

Common causes

• A very high volume of /v1/invoices/validate calls relative to your plan size.
• An automated loop validating the same documents repeatedly.

How to fix it

• Deduplicate or batch validation calls — validate a document once per change, not per poll.
• Upgrade the plan: the fair-use allowance scales with the monthly document quota.
• The allowance resets with the next monthly period. Generate and parse are unaffected.

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.