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 name (bank search)

The name parameter of the bank search (/v1/search) contains a character that is not allowed or is not a text value (e.g. a JSON object). Allowed are the letters A-Z, a-z, Ä, Ö, Ü, ä, ö, ü, ß, digits, space, hyphen, round brackets and comma.

Affected field: name

{
  "error": {
    "http_status": 400,
    "code": "invalid_name",
    "message": "The name field contains invalid characters. Allowed: letters (A-Z, a-z, Ä, Ö, Ü, ä, ö, ü, ß), digits, space, hyphen, parentheses and comma",
    "field": "name"
  }
}

Invalid location (bank search)

The location parameter of the bank search (/v1/search) contains a character that is not allowed or is not a text value (e.g. a JSON object). Allowed are the letters A-Z, a-z, Ä, Ö, Ü, ä, ö, ü, ß, digits, space, hyphen, round brackets and comma.

Affected field: location

{
  "error": {
    "http_status": 400,
    "code": "invalid_location",
    "message": "The location field contains invalid characters. Allowed: letters (A-Z, a-z, Ä, Ö, Ü, ä, ö, ü, ß), digits, space, hyphen, parentheses and comma",
    "field": "location"
  }
}

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 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"
  }
}