API errors

Service not ready

A readiness probe (GET /ready) found that one or more hard dependencies — the database or the KoSIT validator — is unavailable. The API is running but not ready to serve requests that need those dependencies. The response body names each dependency's status. The PDF sidecar is a soft dependency: when only it is down, /ready answers 200 with status "degraded" rather than leaving rotation.

Error type

https://normbill.com/docs/errors/not-ready

HTTP status

503

Common causes

• The database could not be reached (the SELECT 1 probe failed).
• The KoSIT validator sidecar could not be reached.
• The deployment is briefly starting up, or a dependency is restarting.

How to fix it

• Retry after a few seconds — readiness recovers automatically once dependencies are back.
• Check the status page for live component health.
• If the condition persists, contact support@normbill.com.

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.