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"
}| Status | X-Error-Code | Means | What to do |
|---|---|---|---|
| 401 | MISSING_KEY | No Authorization or apikey header | Send the key |
| 401 | INVALID_KEY | Malformed key, or the signature did not match | Check for truncation or a stray space |
| 401 | UNKNOWN_KEY | Well-formed but not a key we issued | Confirm you copied the whole key |
| 401 | KEY_REVOKED | The key was revoked in the portal | Create a new one; stop retrying |
| 401 | ENV_MISMATCH | The key's environment does not match the service it reached | You are probably mixing a test key with live config |
| 401 | ENV_MISSING | The edge did not state an environment — a misconfiguration on our side | Retry; if it persists, contact support |
| 403 | KEY_EXPIRED | The key is past its expiry | Create a new one |
| 429 | RATE_LIMITED | Too many requests this minute | Back off and retry |
| 429 | QUOTA_EXHAUSTED | Monthly quota spent | Wait 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:
| Status | X-Error-Code | Means | What to do |
|---|---|---|---|
| 400 | TEMPLATE_INVALID | A template body has the wrong shape or is over a limit (admin calls only) | The message names the field |
| 400 | INVOICE_INVALID | The invoice body is not a JSON object (413 when over 1 MiB) | Send the invoice object as the body |
| 400 | MALFORMED_BODY | The request body is not valid JSON | Check the serialiser |
| 400 | INVALID_PARAMETER | language is not DE, EN or FR | |
| 403 | ADMIN_REQUIRED | Creating, replacing, deleting or previewing a template needs the admin role | Render with one of the listed templates |
| 404 | TEMPLATE_NOT_FOUND | No template with that id | Pick an id from GET /e-invoice/templates |
| 413 | PAYLOAD_TOO_LARGE | Request body over 8 MiB | Shrink the body |
| 422 | RENDER_REJECTED | The engine rejected the template or the invoice; the message is the engine's | A helper on an empty value, a VAT amount that needs rounding, … |
| 422 | RENDER_TOO_LARGE | The PDF is over 100 pages or 32 MiB | Check for a runaway section |
| 502 | DOCUMENT_SERVICE_ERROR | The engine failed | Retry with backoff |
| 503 | DOCUMENT_SERVICE_UNAVAILABLE | The engine is unreachable or timed out | Retry 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.