Error Codes Reference

Full reference for all INVOICE_ERR_* codes: HTTP status, stage, and when each is triggered.

Every error response uses the same JSON envelope, whether the request was made in binary-PDF mode or ?format=json mode:

json

{
  "error": {
    "code": "INVOICE_ERR_MISSING_FIELD",
    "stage": "validation",
    "message": "Seller VAT ID is required for a VAT invoice.",
    "field": "seller.vatId"
  }
}

The code field is the machine-readable identifier — parse code, not message. message is human-readable and may change between versions. field is a dotted/indexed path to the offending value (e.g. seller.vatId or lineItems[0].taxRate) and is present on field-level errors only. The JSON Schema for this envelope is at GET /v1/schema/error.v1.

stage values

stage is one of input, validation, vat, or render — the pipeline phase where the request failed.

Codes

Code	HTTP	Stage	Meaning
`INVOICE_ERR_INVALID_JSON`	400	input	Request body is not valid JSON.
`INVOICE_ERR_MISSING_FIELD`	422	validation	A legally required field is absent.
`INVOICE_ERR_INVALID_FIELD`	422	validation	Bad currency code, negative quantity, malformed date, or unknown tax category.
`INVOICE_ERR_VAT_INCONSISTENT`	422	vat	e.g. `reverse_charge` with a non-zero `taxRate`.
`INVOICE_ERR_TOO_MANY_LINES`	422	validation	Exceeds the maximum line-item count (200).
`INVOICE_ERR_TOO_MANY_PAGES`	422	validation	Rendered document exceeds the maximum page count (50).
`INVOICE_ERR_UNAUTHORIZED`	401	input	Missing or invalid marketplace key / proxy secret.
`INVOICE_ERR_QUOTA_EXCEEDED`	429	input	Monthly plan cap reached.
`INVOICE_ERR_RATE_LIMITED`	429	input	Per-IP/second burst limit exceeded.
`INVOICE_ERR_RENDER_FAILED`	500	render	PDF rendering failed. Should be rare; logged server-side.
`INVOICE_ERR_INTERNAL`	500	render	Unexpected server error.

`INVOICE_ERR_MISSING_FIELD`

When triggered: A legally required field is missing — e.g. seller.name, seller.address, buyer.name, buyer.address, or a conditionally required field such as seller.vatId on a VAT invoice or buyer.vatId on a reverse_charge line.

Client handling: Read field from the error envelope and populate the missing value. No PDF is produced for a request that fails validation.

`INVOICE_ERR_VAT_INCONSISTENT`

When triggered: taxCategory is zero, exempt, or reverse_charge but taxRate is not "0"; or a reverse_charge line is present without buyer.vatId.

Client handling: Set taxRate to "0" for these categories, and include buyer.vatId whenever any line is reverse_charge.

`INVOICE_ERR_TOO_MANY_PAGES`

When triggered: The rendered document would exceed 50 pages — a DoS guard against pathologically large lineItems arrays or wrapped descriptions, independent of the 200-line-item cap.

Client handling: Split the invoice into multiple documents, or shorten line-item descriptions.

`INVOICE_ERR_QUOTA_EXCEEDED`

When triggered: The caller has used their full monthly quota under their marketplace plan.

Client handling: Upgrade the plan on the marketplace, or wait for the monthly reset. This is a marketplace-enforced limit, not a per-second rate limit.

`INVOICE_ERR_RATE_LIMITED`

When triggered: The per-IP burst rate limit (60 requests/minute) is exceeded. This is a DoS guard, distinct from the monthly quota.

Client handling: Back off and retry. Implement exponential backoff for automated clients.