API errors

Quota exceeded

The included document allowance for your organization is used up for the current billing period. The window is your Stripe billing period, not the calendar month: an annual subscription pools twelve monthly allowances across the year. Only successful generate and parse calls consume it — failed attempts and validation calls never count.

Error type: https://normbill.com/docs/errors/quota-exceeded
HTTP status: 429

Common causes

The plan's included quota is exhausted (Free: 50, Solo: 500, Starter: 2,500, Growth: 12,000, Platform: 75,000 documents per month, ×12 on annual billing).
A test key hit the separate test allowance (1000 requests per billing period, never billed).
On the free plan the quota is a hard stop; there is no overage.

How to fix it

Upgrade the plan in the dashboard, or wait for your next billing period — the response's retry_after_seconds field and the Retry-After header give the exact wait.
On paid plans with metered overage enabled, over-quota invoices are billed per invoice instead of rejected — check your billing settings.
Watch the X-RateLimit-Limit and X-RateLimit-Remaining response headers — and the X-Quota-Warning header, present from 80% usage — to track usage before hitting the limit.

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.