API errors
Failed-generate fair-use allowance exhausted
Failed generate attempts are free and are never billed — that does not change. They are, however, protected by a fair-use allowance of five times your plan's included document quota, because every attempt still runs the full validation pipeline. That allowance is used up for the current period; your billable document quota is untouched.
- Error type
https://normbill.com/docs/errors/generate-failure-fair-use- HTTP status
- 429
Common causes
- An integration retrying the same invalid payload in a loop without applying the fix from the 422 report.
- A very high volume of rejected attempts relative to your plan size — typically a first integration iterating against the validator.
- Requests rejected as 400, 413 or 422 all count. Failures on our side (503) never do.
How to fix it
- Apply the fix from the 422 ValidationReport before retrying — each issue names the exact path in your request JSON and a concrete remedy.
- Iterate against the free browser playground or /v1/invoices/validate while developing, rather than against generate.
- Upgrade the plan: the allowance scales with the included document quota.
- The allowance resets with the next period. Successful generates and parses 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, generate-failure-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.