Error codes

“Try again” means: the request was fine, a later attempt can succeed — for writes with the same Idempotency-Key. “Correct the input” means: an unchanged retry fails again; change the request, the token or the permissions. “Support”: cannot be fixed on your side — report it with the request_id (see Security & support and the threat model).

If the API answers with 500 internal_error or 503 service_unavailable, or requests come back unusually slowly, check the status page first: it shows the current state of the API and of webhook delivery as well as ongoing incidents.

The error.message field of a response is currently in German; the English explanations above are for reference. Programs should always evaluate error.code.

Unknown or foreign ids are always answered with 404 not_found — never with “no permission”. This way the API does not reveal whether an id exists elsewhere. An identifier in the path that is not a UUID at all (/v1/invoices/abc) is a format error instead: 400 validation_error with { "id": ["invalid_uuid"] } in error.details (until 2026-10-07 the API answered 404 here). An address that does not exist (/v1/foo) returns 404 route_not_found in the same error format.

What error.details contains

error.details is optional and absent for most errors. Where it is present it has a fixed shape per error code; the OpenAPI describes it accordingly, and the responses of the individual endpoints in the reference name which details they return.

Details of validation_error

With 400 validation_error, error.message states the first problem in plain words. error.details maps every affected field to a list of codes — the key is the name of the query parameter or body field, for lists in the body with the position (records[2].lease_start). The codes are stable; the message may change.

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Parameter „from“ fehlt (erwartet: YYYY-MM-DD).",
    "details": { "from": ["required"], "to": ["required"], "foo": ["unknown_parameter"] }
  },
  "request_id": "req_…"
}

Earlier raw codes (VALIDATION_INVALID_UUID, date_format_yyyy_mm_dd, date_or_datetime_iso, status_code_or_class, path_prefix_format) are still listed behind the new code for the parameters that used to return them — for positions in lists (ids[1], records[2].lease_start) additionally under the top-level field (ids, records), where they used to appear. English default texts of the validation library (such as “Too small: expected number to be >=1”) are no longer returned; from after to is reported as range_invalid everywhere instead of validation_error.