Error reference

Complete reference of all Beliq API error codes, HTTP statuses, and remediation guidance.

All API errors use the same response shape:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the error",
    "details": {}
  }
}

That includes a request the router refuses before it reaches an endpoint: a URL that does not decode, or a path parameter longer than the router accepts, gets a 400 VALIDATION_ERROR.

Each endpoint caps the size of the request body. The cap is enforced before the body is read, so an oversize request is refused without being parsed or validated, and it never spends a quota unit.

Exceeding the limit returns 413 with code VALIDATION_ERROR:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body exceeds the size limit of 1 MiB for this endpoint. The body was not read, so this is not a validation failure. Send a smaller document."
  }
}

A body within the limit can still be too large for the engine to process. On /v1/generate, /v1/validate, /v1/parse and /v1/convert that is also a 413 with code VALIDATION_ERROR, whose message says the request is within this endpoint’s body size limit but too large to process; the body was read, and a live key’s quota unit is refunded (see the next section). On /v1/send and /v1/receive (preview) the same refusal is a 400 VALIDATION_ERROR that keeps its unit.

The code is the coarse class tag shared by every 4xx an endpoint answers that is not one of the specific codes above; the 413 status is the discriminator. Read the status, not the code, to tell an oversize body from a schema failure.

When a request fails for a reason on our side rather than in your document, the quota unit that request spent goes back. That covers every ENGINE_UNAVAILABLE (503), and the conversion-tool failures on /v1/convert (CONVERSION_TOOL_UNAVAILABLE, CONVERSION_TOOL_ERROR). It also covers a body the engine refused as too large on /v1/generate, /v1/validate, /v1/parse and /v1/convert (a 413, see Request size limits), and two answers of POST /v1/generate for a PDF that was not delivered: a 500 INTERNAL_ERROR when the PDF could not be produced, and a 422 PDFA_VIOLATION, which is about the PDF page and not about your invoice data. It does not cover any other 4xx that names something in your document: that is an answer you asked for, and it keeps its unit. A CONVERSION_OUTPUT_INVALID (422) on /v1/convert keeps its unit as well, whatever made the converted document fail: Beliq validates the output and not the source, so it cannot tell a source that was already invalid from one a converter changed. POST /v1/convert says more.

A DATABASE_UNAVAILABLE (503) is a failure on our side too. If the request had spent a unit, Beliq tries the refund at once. It does the same when the charge itself was cut off and may have gone through. While the database is down that refund usually cannot be applied. Most often the database fails the request before any unit is spent, because the key check comes first: then nothing was charged and there is nothing to refund.

Every response that refunds, or should have, says so on the x-beliq-quota-refunded header:

Refunds are unconditional for the failures where nothing was computed: an unreachable engine, a shed request, a missing conversion tool, a body the engine refused as too large. Where a failure did consume engine compute (a timeout, a fault raised part-way through processing, or a PDF that was built and then not delivered) refunds are capped at 50 per organization per clock hour. The cap exists so a deliberately expensive document cannot be run repeatedly at no cost; normal traffic through a real incident stays well under it. A DATABASE_UNAVAILABLE refund is not capped. If you see x-beliq-quota-refunded: false on volume you consider legitimate, or on any DATABASE_UNAVAILABLE, email hello@beliq.eu with the error.incidentId, or with the x-request-id response header when the answer carries none, and we will reconcile it.

A VALIDATION_ERROR raised by JSON schema validation carries details.fields, one entry per rejected constraint. This is the 400 on POST /v1/generate for a body that fails the schema, and on POST /v1/validate, /v1/parse and /v1/convert for a query string that fails it. A body that passes the schema can still be refused by the engine, for a rule the generate page names, such as a buyer taxId on Factur-X basic: that 400 carries no details, and its message says what was refused. The 400 for a URL the router cannot route carries no details either. The other statuses that share the code (413, 415, and any other 4xx with no more specific code) reject before or outside the schema and carry no details at all.

A missing nested property reports the parent object as path and names the child in message, so { "standard": "xrechnung", "output": "xml", "invoice": { "issueDate": "2026-04-13" } } answers:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "body/invoice must have required property 'number'",
    "details": {
      "fields": [
        {
          "path": "/invoice",
          "message": "must have required property 'number'",
          "keyword": "required"
        }
      ]
    }
  }
}

One bad value can produce several entries. A standard outside the accepted set is checked against each allowed value in turn, so it yields one const entry per candidate plus a closing anyOf entry, all of them on the same path. Read fields as the list of constraints that failed, not as a list of distinct problems, and key your own error reporting on path.

INVALID_INVOICE includes a full validationResult in details, matching the validation result from /v1/validate:

{
  "success": false,
  "error": {
    "code": "INVALID_INVOICE",
    "message": "Invoice validation failed with 1 error",
    "details": {
      "validationResult": {
        "valid": false,
        "format": "cii",
        "schematronVersion": "1.3.16",
        "ciusVersion": "XRechnung-2.6.0",
        "errors": [
          {
            "ruleId": "BR-DE-15",
            "severity": "error",
            "location": "/rsm:CrossIndustryInvoice",
            "message": "An XRechnung invoice must contain a buyer reference (BT-10)."
          }
        ],
        "warnings": []
      }
    }
  }
}

PROFILE_STANDARD_MISMATCH includes the rejected combination so you can correct the request:

{
  "success": false,
  "error": {
    "code": "PROFILE_STANDARD_MISMATCH",
    "message": "Profile 'extended' is not allowed for standard 'peppol-bis'.",
    "details": {
      "standard": "peppol-bis",
      "profile": "extended",
      "allowedProfiles": ["peppol"]
    }
  }
}

DOCUMENT_TYPE_STANDARD_MISMATCH is returned when documentType: "creditnote" is sent for a standard that only supports invoices, notably fatturapa, facturae and ksef. The four EN 16931 hybrid/XML routes peppol-bis, facturx, xrechnung, and zugferd accept CreditNotes, as does the national eslog route (document type code 381 on the same e-SLOG message). Inspect creditNoteCapableStandards in error details; it mirrors the deployed engine capability set.

{
  "success": false,
  "error": {
    "code": "DOCUMENT_TYPE_STANDARD_MISMATCH",
    "message": "documentType='creditnote' is not supported for standard 'fatturapa'. Accepted for CreditNote payloads: ['eslog', 'facturx', 'peppol-bis', 'xrechnung', 'zugferd'].",
    "details": {
      "standard": "fatturapa",
      "documentType": "creditnote",
      "creditNoteCapableStandards": ["eslog", "facturx", "peppol-bis", "xrechnung", "zugferd"]
    }
  }
}

The same code answers a typeCode (BT-3) sent with a standard whose builder writes its own document type: fatturapa, facturae, eslog and ksef. Beliq refuses rather than build the document with the standard’s default code in place of yours, which would send a corrected invoice out as a commercial one. Here details carries typeCode and typeCodeCapableStandards instead of the credit note keys, so read whichever pair is present.

{
  "success": false,
  "error": {
    "code": "DOCUMENT_TYPE_STANDARD_MISMATCH",
    "message": "typeCode='384' is not supported for standard 'fatturapa', whose builder writes its own document type. Accepted for typeCode: ['facturx', 'peppol-bis', 'xrechnung', 'zugferd'].",
    "details": {
      "standard": "fatturapa",
      "typeCode": "384",
      "typeCodeCapableStandards": ["facturx", "peppol-bis", "xrechnung", "zugferd"]
    }
  }
}

POST /v1/generate builds a ZUGFeRD or Factur-X PDF and then runs veraPDF 1.30.3 on the finished file (the PDF/A check on a hybrid PDF). When veraPDF reports a violation of its PDF/A-3b profile, the PDF is not returned and the answer is 422 PDFA_VIOLATION. details.failedRules lists the rules veraPDF reported as failed, at most 20 of them. Each entry holds these keys, under the names and with the values veraPDF’s own report gives them:

{
  "success": false,
  "error": {
    "code": "PDFA_VIOLATION",
    "message": "veraPDF reported a violation of its PDF/A-3b profile in the generated PDF, so the PDF was not returned.",
    "details": {
      "failedRules": [
        {
          "specification": "ISO 19005-3:2012",
          "clause": "6.2.11.4.1",
          "testNumber": 1,
          "description": "The font programs for all fonts used for rendering within a conforming file shall be embedded within that file, as defined in ISO 32000-1:2008, 9.9",
          "failedChecks": 3
        }
      ]
    }
  }
}

The list is veraPDF’s: Beliq adds no rule and rewrites no text. veraPDF is run with a limit on the failed checks it collects for one file, so failedChecks has an upper bound and the list may not hold every rule the file breaks. It keeps of each rule only what veraPDF’s report holds under these five names with these types, so an entry can lack a key and the list can be empty. The answer carries no incidentId.

These are returned only when a pdfTemplateId is referenced on POST /v1/generate. Stored templates are designed in the dashboard and are scoped to your organization, so they require an authenticated request.

{
  "success": false,
  "error": {
    "code": "PDF_TEMPLATE_NOT_FOUND",
    "message": "PDF template k3d-9mp was not found."
  }
}

Every API response includes an x-request-id header (UUID). Quote it to hello@beliq.eu for faster troubleshooting.

x-request-id: 7f3d2a1b-4e5c-6d7f-8a9b-0c1d2e3f4a5b

A 5xx that an endpoint in this reference raises itself additionally carries an error.incidentId in the response body. It links the response directly to the captured error event on our side, so quoting it in a support request is the fastest path to a diagnosis:

{
  "success": false,
  "error": {
    "code": "ENGINE_UNAVAILABLE",
    "message": "The e-invoice processing service is temporarily unavailable. Please try again shortly.",
    "incidentId": "V7mKp2XwQd"
  }
}

Every DATABASE_UNAVAILABLE carries one too, whichever endpoint answers it, GET /v1/me included.

The 503s that refuse a feature that is switched off or has no provider, TRANSMISSION_DISABLED and TRANSMISSION_NO_PROVIDER, carry none: quote the x-request-id header for those.