E-Invoice API
Guides

Errors

Gateway errors, their codes, and the document service's own error format.

Errors come from one of two places, and they look different because they are different systems.

Gateway errors

The gateway sits in front of the document service and rejects requests before they reach it — bad key, no quota, wrong environment. These carry an X-Error-Code response header with a stable, machine-readable reason.

Check that header rather than string-matching on message, which is prose and may be reworded.

{
  "statusCode": 401,
  "message": "API key not valid for this environment",
  "errorCode": "ENV_MISMATCH"
}
StatusX-Error-CodeMeansWhat to do
401MISSING_KEYNo Authorization or apikey headerSend the key
401INVALID_KEYMalformed key, or the signature did not matchCheck for truncation or a stray space
401UNKNOWN_KEYWell-formed but not a key we issuedConfirm you copied the whole key
401KEY_REVOKEDThe key was revoked in the portalCreate a new one; stop retrying
401ENV_MISMATCHThe key's environment does not match the service it reachedYou are probably mixing a test key with live config
401ENV_MISSINGThe edge did not state an environment — a misconfiguration on our sideRetry; if it persists, contact support
403KEY_EXPIREDThe key is past its expiryCreate a new one
429RATE_LIMITEDToo many requests this minuteBack off and retry
429QUOTA_EXHAUSTEDMonthly quota spentWait for the period to roll over, or raise your plan

A request is counted against the quota when it is authorized, before the engine answers: a call the engine then rejects (a 400, a 422 RENDER_REJECTED) or fails (502, 503) still cost one unit. Validate on the sandbox first.

RATE_LIMITED is worth retrying with backoff. QUOTA_EXHAUSTED is not — it will not clear until the month does.

Template API codes

The template endpoints are served by the gateway itself, so their errors use the same shape and header:

StatusX-Error-CodeMeansWhat to do
400TEMPLATE_INVALIDA template body has the wrong shape or is over a limit (admin calls only)The message names the field
400INVOICE_INVALIDThe invoice body is not a JSON object (413 when over 1 MiB)Send the invoice object as the body
400MALFORMED_BODYThe request body is not valid JSONCheck the serialiser
400INVALID_PARAMETERlanguage is not DE, EN or FR
403ADMIN_REQUIREDCreating, replacing, deleting or previewing a template needs the admin roleRender with one of the listed templates
404TEMPLATE_NOT_FOUNDNo template with that idPick an id from GET /e-invoice/templates
413PAYLOAD_TOO_LARGERequest body over 8 MiBShrink the body
422RENDER_REJECTEDThe engine rejected the template or the invoice; the message is the engine'sA helper on an empty value, a VAT amount that needs rounding, …
422RENDER_TOO_LARGEThe PDF is over 100 pages or 32 MiBCheck for a runaway section
502DOCUMENT_SERVICE_ERRORThe engine failedRetry with backoff
503DOCUMENT_SERVICE_UNAVAILABLEThe engine is unreachable or timed outRetry with backoff

Both are 429. Retrying a QUOTA_EXHAUSTED in a loop burns your own rate limit and will never succeed. Branch on X-Error-Code, not on the status.

Document service errors

Once a request is authorized, the document service handles it and reports its own problems — a malformed XML, a PDF that is not PDF/A, a document that fails validation. These are 4xx from the document service itself and carry its own error shape:

{
  "requestUrl": "/api/v1.8.2/e-invoice/validate",
  "httpCode": 400,
  "errorCode": "…",
  "message": "…"
}

The practical distinction: a gateway error means the request never happened. A document service error means it happened and the document was the problem.

Rate limits

Sandbox and live keys are limited separately, and the sandbox is capped harder because it is a public surface. If you are being limited while developing, that is the sandbox's limit — a live key has its own, higher one.

503

503 means the authentication service could not be reached. The gateway fails closed rather than letting unauthenticated traffic through, so this is a temporary outage on our side, not something wrong with your request. Retry with backoff.

On this page