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": {}
  }
}

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 MB for this endpoint. The body was not read, so this is not a validation failure. Send a smaller document."
  }
}

The code is the coarse class tag shared by every 4xx 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 does not cover a 4xx that names something in your document: that is an answer you asked for, and it keeps its unit.

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. Where a failure did consume engine compute — a timeout, or a fault raised part-way through processing — 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. If you see x-beliq-quota-refunded: false on volume you consider legitimate, email hello@beliq.eu with the error.incidentId 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; 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 and facturae. 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"]
    }
  }
}

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

Server-side failures (HTTP 500 and 503) additionally carry 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"
  }
}