Errors and limits
Status codes
Section titled “Status codes”The HTTP status codes are stable. Typical answers:
| Status | Meaning |
|---|---|
| 200, 201 | success |
| 400 | invalid request (missing or invalid field, not a PDF) |
| 401 | API key missing, expired or revoked |
| 403 | the key lacks a right, may not use this company, or the route is not available to keys |
| 404 | not found, outside the key’s access or company |
| 409 | conflict, with a code |
| 413 | the uploaded file is larger than 20 MB |
| 429 | too many requests; Retry-After gives the seconds |
| 5xx | server error, try again later |
Error body
Section titled “Error body”Errors are JSON:
{ "statusCode": 409, "message": "Plain text in German", "error": "Conflict", "code": "approval.external_conflict", "params": { "status": "approved" }}messageis plain text in German. Do not parse it.codeis a stable error code where one is assigned, for exampleapproval.external_conflict. Self-service routes (expenses, travel, own bank details) carry a code for the interface to translate. More routes get codes as they are needed.paramsholds parameters for the code, for examplestatus.
Limits
Section titled “Limits”- File: one PDF (or e-invoice XML) per upload, at most 20 MB. Above that the API answers 413.
- Rate: at most 60 uploads per minute per key, and at most 600 calls per minute per address under
/api. Above that the API answers 429 withRetry-After(seconds). A job should deliver serially, wait the given time on 429 and retry with a delay on 5xx. - Lists:
pageSizeat most 500; events at most 200 per call.
Health
Section titled “Health”GET /api/health needs no key. It shows the status, the version and unfinished work. It answers 503 if the database or the queue do not respond. See Reference: operations.
Machine-readable description
Section titled “Machine-readable description”The OpenAPI document (OpenAPI 3.0) describes this surface with the schemas from the contracts of the code. It is generated from the code, and a test keeps it current: what it says applies.