API errors

Overage spending cap reached

Your plan's included documents are used up and the metered overage has hit its spending cap for the current billing period. The cap protects you from bill shock: it is 2× the base fee that period actually charges — 2× the monthly price on monthly billing, 2× the annual price on annual billing.

Error type

https://normbill.com/docs/errors/overage-cap-reached

HTTP status

429

Common causes

• An unusually high-volume period consumed the full quota plus the capped overage allowance.
• The default overage cap (2× the base fee invoiced for this period) has not been raised for your organization.

How to fix it

• Upgrade to a larger plan — the included volume rises and the cap rises with the base fee.
• Contact support to raise the cap for your organization if the volume is expected.
• The cap resets with your next billing period; retry_after_seconds gives the exact wait.

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.