eliDocs
/
API Reference

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": {}
  }
}
Field Type Description
code string Stable, machine-readable error code
message string Human-readable explanation
details object? Additional structured data (e.g. validation results for INVALID_INVOICE)
incidentId string? Support correlation ID, present on 5xx responses only. Quote it together with the x-request-id header when contacting support

Error codes

Code HTTP Status Meaning Endpoints Remediation
VALIDATION_ERROR 400 Request body is invalid All Check required fields and types in the generate schema
INVALID_INVOICE 422 Invoice data is structurally valid JSON but fails validation: EN 16931 or CIUS Schematron for UBL/CII, or authority XSD for Italy FatturaPA /v1/generate Inspect details.validationResult.errors (and for FatturaPA, structural XSD findings where applicable)
PROFILE_STANDARD_MISMATCH 422 The chosen profile is not allowed for the chosen standard /v1/generate Use a compatible combination — the response details includes standard, profile, and allowedProfiles. See the profile compatibility table.
DOCUMENT_TYPE_STANDARD_MISMATCH 422 documentType: "creditnote" with a standard that does not accept CreditNote payloads — today fatturapa and facturae (invoices only). /v1/generate Inspect details.creditNoteCapableStandards; it lists standards that honour CreditNotes in the deployed engine (facturx, peppol-bis, xrechnung, zugferd, eslog). See the Peppol Credit notes section.
UNSUPPORTED_FORMAT 400 The requested standard/profile/output combination is not supported /v1/generate Check the supported combinations table
PARSE_FAILED 422 Input file could not be parsed as a valid e-invoice /v1/parse Verify the input is a well-formed UBL 2.1 or CII XML, or a ZUGFeRD / Factur-X hybrid PDF with an embedded CII attachment. FatturaPA and SDI messaggio inputs are not handled by parse — use /v1/validate for those.
INVALID_XML 422 Input XML is malformed or fails schema validation /v1/validate, /v1/parse Fix XML syntax and ensure it conforms to one of: UBL 2.1, CII D16B / D22B, Italy FatturaPA XSD graph (v1.4 runtime bundle) on /v1/validate, or Italy SDI MessaggiTypes v1.1 on /v1/validate
AUTHENTICATION_REQUIRED 401 No API key provided or key format is invalid All /v1/* Include Authorization: Bearer <key> or X-API-Key: <key> in the request headers
INVALID_API_KEY 403 API key does not exist or has been revoked All /v1/* Verify the API key in the dashboard. Generate a new key if it was revoked
QUOTA_EXCEEDED 429 Monthly usage quota exhausted /v1/generate, /v1/validate, /v1/parse Upgrade your subscription plan in the dashboard, or wait until the next billing period (Retry-After is the seconds until the next UTC calendar month)
RATE_LIMITED 429 Too many requests in a short time window All Respect Retry-After and retry with backoff
ENGINE_UNAVAILABLE 503 The e-invoice engine is temporarily unavailable /v1/generate, /v1/validate, /v1/parse Retry after a short delay. If persistent, check the status page and contact support with the error.incidentId value
INTERNAL_ERROR 500 Unexpected server error All Retry the request. If persistent, contact support with the error.incidentId value and the x-request-id response header
PDF_TEMPLATE_AUTH_REQUIRED 400 pdfTemplateId was sent without an authenticated organization. Stored PDF templates are org-scoped, so they require an API key (the free, unauthenticated generator can use template: "standard" instead). /v1/generate Send the request with your Authorization: Bearer <key>, or drop pdfTemplateId and use template: "standard" for the built-in layout
PDF_TEMPLATE_NOT_FOUND 404 The referenced pdfTemplateId does not exist in your organization /v1/generate Check the template’s ref in the dashboard under PDF templates
PDF_TEMPLATE_INVALID 422 The stored template definition could not be parsed /v1/generate Re-save the template in the dashboard designer; if it persists, contact support with the x-request-id

Transmission errors (preview)

Code HTTP Status Meaning Remediation
TRANSMISSION_DISABLED 503 Transmission is not enabled on this deployment. Returned by every transmission endpoint until managed delivery launches. Build and validate the file today and deliver it through your own channel. Subscribe for the launch date.
IDEMPOTENCY_KEY_REUSED 409 An Idempotency-Key was reused with a different request body. Use a fresh key for a different document, or resend the identical body to get the existing transmission back. See Idempotency.
INBOX_UNKNOWN_PROVIDER 404 An inbound network callback referenced a provider that is not registered. Provider-side authentication error, not reachable with an API key.
INBOX_VERIFICATION_FAILED 401 An inbound network callback or document failed signature verification. Provider-side authentication error, not reachable with an API key.

HTTP status code summary

Status Meaning
200 Success
400 Bad request: invalid JSON, missing required fields, or unsupported format combination
401 Unauthorized: no API key or invalid key format
403 Forbidden: API key is revoked or does not exist
404 Not found: a referenced resource (e.g. a pdfTemplateId) does not exist in your organization
409 Conflict: an Idempotency-Key was reused with a different body (transmission, preview)
422 Unprocessable entity: input is syntactically valid but fails business rules or parsing
429 Too many requests: quota exceeded or rate limited
500 Internal server error
503 Service unavailable: engine is temporarily down, or transmission is not enabled

INVALID_INVOICE details

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.5.0",
        "errors": [
          {
            "ruleId": "BR-DE-1",
            "severity": "error",
            "location": "/rsm:CrossIndustryInvoice",
            "message": "An XRechnung invoice must contain a buyer reference (BT-10)."
          }
        ],
        "warnings": []
      }
    }
  }
}

PROFILE_STANDARD_MISMATCH details

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 details

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: ['facturx', 'peppol-bis', 'xrechnung', 'zugferd'].",
    "details": {
      "standard": "fatturapa",
      "documentType": "creditnote",
      "creditNoteCapableStandards": ["facturx", "peppol-bis", "xrechnung", "zugferd"]
    }
  }
}

PDF template errors

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.

Code When Fix
PDF_TEMPLATE_AUTH_REQUIRED pdfTemplateId sent on an unauthenticated request Use your API key, or switch to template: "standard"
PDF_TEMPLATE_NOT_FOUND The ref is not a template in your organization Verify the ref in the dashboard
PDF_TEMPLATE_INVALID The stored definition is corrupt and cannot be rendered Re-save the template in the designer 
{
  "success": false,
  "error": {
    "code": "PDF_TEMPLATE_NOT_FOUND",
    "message": "PDF template k3d-9mp was not found."
  }
}

Request ID and incident ID

Every API response includes an x-request-id header (UUID). Share this value with support 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"
  }
}