Skip to content

Errors and limits

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

Errors are JSON:

{
"statusCode": 409,
"message": "Plain text in German",
"error": "Conflict",
"code": "approval.external_conflict",
"params": { "status": "approved" }
}
  • message is plain text in German. Do not parse it.
  • code is a stable error code where one is assigned, for example approval.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.
  • params holds parameters for the code, for example status.
  • 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 with Retry-After (seconds). A job should deliver serially, wait the given time on 429 and retry with a delay on 5xx.
  • Lists: pageSize at most 500; events at most 200 per call.

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.

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.