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 daily fair-use budget, because every attempt still runs the full validation pipeline. The budget is a whole month's included documents times five, available every UTC day (the free plan's 50 documents/month give 250 rejected attempts per day), and it refills at 00:00 UTC — retry_after_seconds is never more than a day. 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 in one day relative to your plan size — typically a bulk migration pushing a systematic mistake, or a first integration iterating against the validator.
- Only attempts that actually ran the validation pipeline and came back rejected count — in practice the 422 responses. Requests turned away before the pipeline (400 invalid-request, or a body over the 2 MB transport limit) and failures on our side (503) never count.
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.
- Wait for the reset: the budget refills at 00:00 UTC, and the Retry-After header tells you exactly when.
- Upgrade the plan: the daily budget scales with the plan's included document volume.
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.