Status codes and error handling
Every failed request returns a structured JSON error you can act on programmatically. This page covers the response envelope, the error categories, and how to handle them in code.
status for the HTTP outcome, branch on errorCode for the category, and you have handled every error the API can return.
The error envelope
Every error response, on every endpoint, contains the same top-level fields:
| Field | Type | Description |
|---|---|---|
| type | string | RFC 7807 type URI for the error class. |
| title | string | Short, human-readable summary of the error class. |
| status | int | The HTTP status code, repeated in the body for convenience. |
| errorCode | int | The InvoiceXML category code. This is the one value to branch on. |
| detail | string | Longer human-readable explanation, safe to show to end users. |
| errors | array | An array of finding objects, one per fault. Present on validation failures and on every error that names a fault in your input (4001, 4002, 4006, 4015, 4017, 4018), always in the same shape. |
| warnings | array | Non-blocking findings, same object shape as a 4001 finding. Advisory only, they never cause a request to fail. |
Error codes
The errorCode identifies the category of error. Branch on it to decide how to handle the response. The errors column shows what, if anything, the errors field carries for that code.
| errorCode | Name | Description | errors |
|---|---|---|---|
| 4000 | General Error | An unclassified processing error. Check title and detail for information. |
none |
| 4001 | XML Validation | The invoice XML violates EN 16931 Schematron business rules (e.g. BR-01, BR-CO-15), or does not conform to the declared profile's official schema. Each violation is a finding object. | errors[] |
| 4002 | Model Validation | One or more request fields are missing or malformed before processing could start. Also returned when specificationId declares a header-only profile (MINIMUM or BASIC WL) and the supplied header totals contradict the line items, or carry a rounding amount (BT-114): the subset XML drops the line evidence, so its totals must be internally consistent. Also returned when validationLanguage is anything other than en, de or fr (see Localized error messages). |
errors[] |
| 4003 | Missing File | A multipart endpoint expected a file upload but none was provided. Include the file in the request. | none |
| 4004 | Unsupported Content Type | The uploaded file's content type or extension is not accepted by that endpoint (for example, a non-PDF where a PDF is required). A logo (logo or logoUrl) that is not a usable PNG or JPEG is rejected the same way, with a title naming the field. |
none |
| 4005 | File Too Large | Returned with HTTP 413. The uploaded file exceeds the 20 MB size limit, or a logo (logo or logoUrl) exceeds 2 MB. Also returned when a PDF you supply as the visual layer of a hybrid invoice, the pdf part of /v1/embed/* or the file at pdfUrl, has more than 100 pages; the detail names the page count. Remove blank pages, which spreadsheet exports often add, and send it again. |
none |
| 4006 | No Embedded XML | The PDF does not contain an embedded Factur-X / ZUGFeRD XML attachment. Returned by /v1/extract/* and by the /v1/convert/facturx/to/* and /v1/convert/zugferd/to/* endpoints, with a single PDF-EMBED finding. The validate endpoints answer the same case with a normal verdict (valid: false, rule PDF-EMBED) instead. To read a PDF without embedded XML, use /v1/parse/json. |
errors[] |
| 4007 | PDF Error | The PDF could not be processed. It may be corrupted, password-protected, or not a valid invoice PDF. | none |
| 4008 | Not an Invoice | The uploaded document does not appear to be an invoice. Returned by AI-powered endpoints (e.g. /v1/parse/json, /v1/transform/to/*) when classification rejects the input. |
none |
| 4009 | Multiple Invoices | The uploaded PDF contains more than one invoice. Split it and resubmit one invoice per file. | none |
| 4010 | Unauthorized | The Authorization header is missing, malformed, or carries an unknown / revoked API key. Re-check the bearer token and retry. |
none |
| 4011 | Remote Fetch Error | A pdfUrl or logoUrl supplied to a create endpoint could not be fetched: it was not a valid http/https URL, resolved to a blocked address, or the host was unreachable. Content of the wrong type (not a PDF, or not a PNG/JPEG for logoUrl) is 4004 and an oversized file is 4005. |
none |
| 4013 | No Attachments | The invoice contains no embedded attachments (BG-24 with a BT-125 payload). Returned with HTTP 404 by /v1/extract/attachments. Documents referenced only by external URI (BT-124) are not downloaded. |
none |
| 4014 | Invalid Attachment | An embedded attachment (BT-125) could not be base64-decoded, so the invoice XML carries a corrupt payload. Returned by /v1/extract/attachments; the detail names the offending document reference. |
none |
| 4015 | Unembeddable Font | The supplied PDF uses fonts with no embedded font program that could not be embedded automatically, and PDF/A-3 requires every font to be embedded. Re-export the PDF with fonts embedded (most PDF tools call this option "embed fonts") and retry; each offending font is one PDF-FONTS finding. |
errors[] |
| 4016 | Remote Fetch Forbidden | The server hosting your pdfUrl or logoUrl answered HTTP 403 and refused the download, typically a firewall or WAF (for example Cloudflare) blocking server-to-server requests. Fix it by allowlisting your PDF URL fetch token: add a firewall rule that permits requests carrying the X-InvoiceXML-Token header with the token shown on your authentication page. |
none |
| 4017 | Unsupported ZUGFeRD/Factur-X Profile | The invoice's Specification identifier (BT-24) is not one of the profile URNs defined by the ZUGFeRD/Factur-X specification, so no compliant hybrid PDF can be produced: the profile is mirrored into the PDF/A-3 metadata as the conformance level, which only allows the official profiles. Returned by /v1/embed/facturx and /v1/embed/zugferd. Declare an official profile URN, for example urn:cen.eu:en16931:2017 (EN 16931). Watch the keyword: the EXTENDED profile uses #conformant# where the narrower profiles use #compliant#. |
errors[] |
| 4018 | Unsupported Order-X Profile | The Order-X counterpart of 4017: the order's guideline identifier is not one of the three URNs the Order-X specification defines (urn:order-x.eu:1p0:basic, :comfort, or :extended), so the conformance level cannot be mirrored into the PDF/A-3 metadata. Returned by /v1/create/order-x. |
errors[] |
| 4019 | Too Many Requests | More requests of your account are in progress at the same time than your plan allows, and this one could not be started in time. The email delivery endpoints (/v1/create/{format}/email and /v1/embed/{format}/email) also answer with it when too many emails are being sent at once. The only error that comes with HTTP 429 instead of 400. Wait the number of seconds in the Retry-After header and send the same request again. See Concurrent requests for batching and retry patterns. |
none |
| 4020 | Email Not In Plan | Your plan does not include email delivery. Returned with HTTP 403 by the email delivery endpoints, checked on every call. Nothing was created or sent. |
none |
| 4021 | Email Sending Disabled | Email sending is switched off or paused for your account. Returned with HTTP 403 by the email delivery endpoints. Nothing was sent; contact [email protected]. |
none |
| 4022 | Sending Domain Not Verified | The domain of the sender address (email.from) has not finished verification yet. Returned by the email delivery endpoints. Nothing was sent: check the domain's status on the Verified email domains page of your dashboard and send again once it shows Verified. A sender on a domain you have not added at all is a 4002 on email.from instead. |
none |
| 4023 | Processing Timeout | The request took longer than 90 seconds and was stopped. Returned with HTTP 503 by any endpoint. Send the same request again. |
none |
| 4024 | Totals Mismatch | What the lines, allowances, charges and VAT read from the document add up to differs from the total it prints by more than a few cents, or no total or no lines could be read, so no invoice was produced. Returned by /v1/transform/to/*, with a single TOTALS-MISMATCH finding that names both amounts. invoiceData holds the document as read: correct it and send it to /v1/create/*. The call uses a credit, and so does sending the same PDF again. |
errors[] |
Example responses
The envelope is identical in all of them. Every error that names a fault in your input (4001, 4002, 4006, 4015, 4017, 4018 and 4024) carries the very same errors array of finding objects, so you handle them all with one code path. The remaining error codes carry no errors field at all.
XML validation, errorCode 4001
The generated or uploaded XML violates EN 16931 Schematron rules. errors is an array of finding objects, one per violated rule.
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "Validation Failed",
"status": 400,
"errorCode": 4001,
"detail": "The invoice contains 2 validation error(s).",
"errors": [
{
"rule": "BR-01",
"layer": "en16931",
"line": null,
"message": "Enter the specification identifier, which names the standard the invoice follows, for example urn:cen.eu:en16931:2017.",
"btCodes": ["BT-24"],
"fields": ["specificationId"],
"raw": "[BR-01] EN16931: An invoice shall have a specification identifier."
},
{
"rule": "PEPPOL-EN16931-R010",
"layer": "cius",
"line": null,
"message": "Peppol BIS requires a buyer electronic address. Add the buyer's electronic address (a buyer VAT identifier is used as a fallback), or use the plain en16931 profile if the invoice is not meant for Peppol.",
"btCodes": ["BT-49"],
"fields": ["buyer.electronicAddress"],
"raw": "[PEPPOL-EN16931-R010] CIUS: Buyer electronic address MUST be provided"
}
],
"warnings": []
}
Each finding is self-describing. Use message for end-user display and raw for debugging or logs. The btCodes and fields arrays let you map a finding back to a form input.
| Field | Type | Description |
|---|---|---|
| rule | string | The validated rule identifier, e.g. BR-01. null for a request check (4002) that enforces no rule. |
| layer | string | null | Validation layer that produced the finding: xsd (structure), en16931 (European core rules), or cius (the profile overlay: Peppol BIS, XRechnung, NLCIUS, PINT, or the Factur-X/ZUGFeRD profile rules). null on 4002 findings, which have no validation layer. |
| line | int | null | 1-based invoice line number, or null for a document-level finding. |
| message | string | Plain-language explanation, safe to show end users. In English unless validationLanguage asks for German or French. |
| btCodes | string[] | EN 16931 Business Term codes the rule references. |
| fields | string[] | Dotted JSON paths into the invoice the finding maps to. Line-scoped paths use a zero-based index (line 3 maps to lines[2]). |
| raw | string | Verbatim validator output, including the rule id, layer and XPath location. |
Map findings straight to your form
fields or btCodes to the matching input, mark it invalid, and show the friendly message beside it. The user is taken straight to the field that needs fixing, with no XPath decoding.
Model validation, errorCode 4002
A request field is missing or malformed, so processing never started. errors is the exact same flat array of finding objects as 4001. rule names the EN 16931 or CIUS rule the check enforces when there is one (BR-06 for a missing seller name) and is null otherwise; layer and raw are null (model validation runs no Schematron), while btCodes and fields are resolved from the field path, so the finding maps to the offending input by both BT code and JSON path.
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"errorCode": 4002,
"valid": false,
"detail": "The request failed validation with 2 error(s).",
"errors": [
{
"rule": "BR-06",
"layer": null,
"line": null,
"message": "Enter the seller name.",
"btCodes": ["BT-27"],
"fields": ["seller.name"],
"raw": null
},
{
"rule": "BR-22",
"layer": null,
"line": 1,
"message": "Enter the quantity of this line.",
"btCodes": ["BT-129"],
"fields": ["lines[0].quantity"],
"raw": null
}
],
"warnings": []
}
Other errors, errorCode 4000, 4003 to 4024
Missing-file, unsupported content type, file-size, PDF-processing, remote-fetch, attachment, too-many-requests, email delivery (4020 to 4022) and processing-timeout (4023) errors carry no errors field. The title and detail tell you what happened. The no-embedded-XML (4006), font-embedding (4015), unsupported-profile (4017 and 4018) and totals-mismatch (4024) errors do carry the errors findings array, in the same shape as 4001: one finding per fault, with its own rule identifier such as PDF-EMBED.
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "Missing File",
"status": 400,
"errorCode": 4003,
"detail": "No file was provided in the request."
}
Warnings never fail a request
warnings array uses the exact same finding shape as 4001 errors, but it is advisory. A response can be successful and still carry warnings. Only entries in errors make a request fail.
Handling errors in code
Parse the JSON body and branch on errorCode. Because every error that carries findings shares the same errors array, they need just one branch between them; 4019 and 4023 are the codes worth a retry; every other code falls through to a generic handler.
const response = await fetch(apiUrl, { method: 'POST', body: formData });
if (!response.ok) {
const problem = await response.json();
switch (problem.errorCode) {
case 4001: // XML validation, profile schema or Schematron rule violations
case 4002: // Model validation, malformed request fields
case 4006: // PDF without an embedded invoice XML (try /v1/parse/json)
case 4015: // PDF fonts that cannot be embedded
case 4017: // BT-24 profile URN outside the ZUGFeRD/Factur-X spec
case 4018: // Guideline URN outside the Order-X spec
case 4024: // Amounts read from a PDF do not add up (fix invoiceData, send it to /v1/create)
// All return the same flat array of finding objects.
problem.errors.forEach(f => {
const where = f.line != null ? `line ${f.line}` : 'document';
console.error(`${where}: ${f.message}`);
// f.fields and f.btCodes map the finding to a form input
});
break;
case 4019: { // Too many requests in progress, or emails at once
// Wait for Retry-After, then send the very same request again
// (see Concurrent requests for a complete retry loop).
const seconds = Number(response.headers.get('Retry-After')) || 10;
await new Promise(resolve => setTimeout(resolve, seconds * 1000));
break;
}
case 4023: // Took too long and was stopped
// Send the same request again; if it keeps timing out, check your document.
break;
default: // remaining codes: no errors array, use title + detail
console.error(`${problem.title}: ${problem.detail}`);
}
}
Localized error messages
The message of every finding can be written in English, German or French, so you can
show it to your users as it is. English is the default; ask for another language per request with
validationLanguage:
| Endpoints | Where to set it |
|---|---|
| /v1/create/* | options.validationLanguage in the JSON body, on every create endpoint including /v1/create/order-x and /v1/create/cio. |
| /v1/validate/*, /v1/embed/*, /v1/convert/*, /v1/transform/* | The validationLanguage form field, next to the uploaded file. On the /v1/validate/*/report endpoints it words the whole PDF report. |
| /v1/extract/*, /v1/parse/json, /v1/render/* | Nowhere. These endpoints validate nothing, so they ignore the field. |
The value is exactly en, de or fr,
in any letter case. Regional tags such as de-DE or fr-BE, and any
other value, are rejected with a 400 (errorCode 4002) carrying one finding whose
fields is ["options.validationLanguage"] on the create endpoints or
["validationLanguage"] on the multipart endpoints.
The setting words the message of every finding in errors and
warnings: request checks (4002), business rule findings (4001), and the API's own findings
such as PROFILE-SCOPE, PROFILE-DETECTION,
PDF-EMBED, ZUGFERD-PROFILE and PDF-FONTS.
Everything else is the same in every language: rule, layer,
line, btCodes, fields,
raw (the validator's verbatim English output), and the problem's title
and detail, which stay English. On the validate endpoints the setting also names the business
terms of the report rows (name; key on code,
which is the same in every language). A missing seller name with
validationLanguage=de:
{
"rule": "BR-06",
"layer": "en16931",
"line": null,
"message": "Geben Sie den Namen des Verkäufers an.",
"btCodes": ["BT-27"],
"fields": ["seller.name"],
"raw": "[BR-06] EN16931: An invoice shall contain the seller name."
}
German and French messages exist for every EN 16931 business rule, the XRechnung (KoSIT) rules, the Peppol BIS content
rules and German national rules, the French CTC rules (BR-FR), and the API's own checks.
Rules without a curated message, such as the CII-SR and UBL-SR syntax rules and other countries' Peppol rules, keep the
rule set's own English wording in every language. BR-FR findings follow the setting
like every other rule: English by default, French with validationLanguage=fr. The
setting is independent of options.language, which sets the language of the invoice itself.
Match on rule, btCodes and fields, never on the message
message depends on the language you ask for, while the rule id, the BT codes and
the field paths are identical in all three. Key your error handling and form mapping on those, and use
message only for display.