All errors are returned as a JSON object with the key error. In most cases, the response body has the following structure:

{
  "error": {
    "http_status": 401,
    "code": "invalid_key",
    "message": "The API key is not valid",
    "field": "..."        // optional – only for input errors
  }
}

Individual error codes can be linked to directly, e.g. /api/docs/errors#invalid_key.

Invalid API key

The bearer token provided is not valid or is missing entirely. Check the Authorization header.

{
  "error": {
    "http_status": 401,
    "code": "invalid_key",
    "message": "The API key is not valid"
  }
}

Invalid IBAN

The IBAN provided is too short, does not start with two letters, or contains invalid characters. Spaces are removed automatically and lowercase letters are normalized - all other special characters are not allowed.

Affected field: iban

{
  "error": {
    "http_status": 400,
    "code": "invalid_iban",
    "message": "The IBAN is invalid or has an incorrect format",
    "field": "iban"
  }
}

Invalid BIC

The BIC provided does not match the ISO 9362 format: 8 or 11 characters, the first six being letters (bank and country code), followed by letters or digits (location code, optionally a three-character branch code). Whitespace is removed and lowercase letters are normalised. A formally valid BIC that does not match the IBAN is not a request error; it returns HTTP 200 with status: 2.

Affected field: bic

{
  "error": {
    "http_status": 400,
    "code": "invalid_bic",
    "message": "The BIC is invalid or has an incorrect format",
    "field": "bic"
  }
}

Invalid account number

The account number was not provided, is zero, or contains non-numeric characters.

Affected field: kontonummer

{
  "error": {
    "http_status": 400,
    "code": "invalid_kontonummer",
    "message": "Account number is missing or contains invalid characters",
    "field": "kontonummer"
  }
}

Invalid bank code (BLZ)

The bank code was not provided or contains non-numeric characters. A valid German bank code (BLZ) is 8 digits and purely numeric.

Affected field: bankleitzahl

{
  "error": {
    "http_status": 400,
    "code": "invalid_blz",
    "message": "Bank code (BLZ) is missing or contains invalid characters",
    "field": "bankleitzahl"
  }
}

Invalid batch size

The ibans array in the POST body is empty or contains more than 500 entries. 1 to 500 IBANs are allowed per request.

{
  "error": {
    "http_status": 400,
    "code": "batch_size_invalid",
    "message": "Batch must contain 1 to 500 IBANs"
  }
}

Invalid batch format

The ibans field is present in the POST body but is not an array (e.g. a single string instead of a list). Use the iban field instead for a single check, or ibans as an array with 1 to 500 entries for a batch check.

Affected field: ibans

{
  "error": {
    "http_status": 400,
    "code": "invalid_batch_ibans",
    "message": "The 'ibans' field must be an array of IBANs",
    "field": "ibans"
  }
}

Conflicting IBAN fields

The POST body to /v1/iban contains both iban (single check) and ibans (batch check) at the same time. Use only one of the two fields per request.

{
  "error": {
    "http_status": 400,
    "code": "conflicting_iban_fields",
    "message": "iban and ibans must not be sent at the same time"
  }
}

Wrong content type

POST requests to /v1/kto, /v1/iban, or /v1/search without path parameters require Content-Type: application/json. Other content types (e.g. application/x-www-form-urlencoded) are not supported.

{
  "error": {
    "http_status": 400,
    "code": "invalid_content_type",
    "message": "POST requests to this endpoint require Content-Type: application/json"
  }
}

Request body too large

The request body exceeds the limit of 128 KB.

{
  "error": {
    "http_status": 413,
    "code": "payload_too_large",
    "message": "The request body is too large (max. 128 KB)"
  }
}

Invalid postal code (bank search)

The zip parameter of the bank search (/v1/search) contains non-numeric characters.

Affected field: zip

{
  "error": {
    "http_status": 400,
    "code": "invalid_zip",
    "message": "Postal code must contain digits only for search",
    "field": "zip"
  }
}

Invalid JSON request body

The request body is valid JSON but not an object (e.g. an array) instead of {...}. Syntactically broken JSON instead returns invalid_request. An empty body does not trigger this error, but instead leads to the matching field error (e.g. invalid_kontonummer).

{
  "error": {
    "http_status": 400,
    "code": "invalid_json",
    "message": "The request body is not a valid JSON object"
  }
}

No search criterion provided

The bank search (/v1/search) was called without any search field. At least one of the fields name, location, zip, or bankleitzahl must be set.

{
  "error": {
    "http_status": 400,
    "code": "missing_search_criteria",
    "message": "At least one of the fields name, location, zip or bankleitzahl must be provided"
  }
}

Invalid max parameter

The max parameter of the bank search is set but is not purely numeric or is outside the allowed range of 1-50. If max is missing or empty, the default of 10 applies instead - that is not an error.

Affected field: max

{
  "error": {
    "http_status": 400,
    "code": "invalid_max",
    "message": "The max parameter must be between 1 and 50",
    "field": "max"
  }
}

Invalid sepa parameter

The sepa parameter is set but is neither 0 nor 1. If sepa is missing, the default 0 applies instead - that is not an error.

Affected field: sepa

{
  "error": {
    "http_status": 400,
    "code": "invalid_sepa",
    "message": "The sepa parameter must be 0 or 1",
    "field": "sepa"
  }
}

Invalid request

Generic error code for two cases with an identical response format but different message text:

1. Path does not match any known endpoint pattern - e.g. /v1/kto/… or /v1/iban/… with extra or missing segments. Only used when no more specific code (e.g. invalid_kontonummer, invalid_iban) applies.

{
  "error": {
    "http_status": 400,
    "code": "invalid_request",
    "message": "Invalid request"
  }
}

2. Request body is not valid JSON (syntactically broken or truncated). Not to be confused with invalid_json, which only applies to syntactically valid JSON that is not an object.

{
  "error": {
    "http_status": 400,
    "code": "invalid_request",
    "message": "The request could not be processed. Most common cause: the request body is not valid JSON."
  }
}

Method not allowed

The HTTP method used is not allowed for this endpoint. Use the method given in the Allow response header.

Affects: all endpoints - e.g. POST to a GET-only endpoint such as GET /v1/kto/{kontonummer}/{bankleitzahl}.

{
  "error": {
    "http_status": 405,
    "code": "method_not_allowed",
    "message": "Method not allowed. Allowed: GET"
  }
}

Access denied

Access to this resource is not allowed.

{
  "error": {
    "http_status": 403,
    "code": "forbidden",
    "message": "Access to this resource is not allowed."
  }
}

Not found

The requested resource does not exist.

{
  "error": {
    "http_status": 404,
    "code": "not_found",
    "message": "The requested resource was not found."
  }
}

Unexpected server error

An unexpected server error, e.g. from an incompletely transmitted request body. The request can usually be retried unchanged. If the error persists, please contact support.

{
  "error": {
    "http_status": 500,
    "code": "internal_error",
    "message": "An unexpected server error occurred."
  }
}

Internal processing error

The check could not be performed server-side. The request was syntactically correct - please retry the request. If the error persists, please contact support.

{
  "error": {
    "http_status": 500,
    "code": "ckonto_failed",
    "message": "cKonto could not be executed"
  }
}

Server busy

All processing slots for checks are currently in use (limit of concurrent checks reached). The request was neither processed nor counted. Resend it unchanged after the number of seconds given in the Retry-After response header.

Retry-After: 2

{
  "error": {
    "http_status": 503,
    "code": "server_busy",
    "message": "Server busy, please retry"
  }
}

Server configuration incomplete

The API could not load its server configuration. This is not caused by your request; retrying the request will not change anything. Please contact support if this error persists.

{
  "error": {
    "http_status": 500,
    "code": "configuration_error",
    "message": "Server configuration incomplete"
  }
}