Fehlerformat
Alle Fehler werden als JSON-Objekt mit dem Schlüssel error zurückgegeben. In den allermeisten Fällen hat der Response-Body folgende Struktur:
{
"error": {
"http_status": 401,
"code": "invalid_key",
"message": "The API key is not valid",
"field": "..." // optional – only for input errors
}
}Einzelne Fehlercodes können direkt verlinkt werden, z. B. /api/docs/errors#invalid_key.
Authentifizierungsfehler
Ungültiger API-Schlüssel
Der übergebene Bearer-Token ist nicht gültig oder fehlt vollständig. Prüfen Sie den Authorization-Header.
{
"error": {
"http_status": 401,
"code": "invalid_key",
"message": "The API key is not valid"
}
}Eingabefehler
Ungültige IBAN
Die übergebene IBAN ist zu kurz, beginnt nicht mit zwei Buchstaben oder enthält ungültige Zeichen. Leerzeichen werden automatisch entfernt und Kleinbuchstaben normalisiert — alle anderen Sonderzeichen sind nicht erlaubt.
Betroffenes Feld: iban
{
"error": {
"http_status": 400,
"code": "invalid_iban",
"message": "The IBAN is invalid or has an incorrect format",
"field": "iban"
}
}Ungültige BIC
Die übergebene BIC entspricht nicht dem Format nach ISO 9362: 8 oder 11 Zeichen, davon die ersten sechs Buchstaben (Bank- und Ländercode), danach Buchstaben oder Ziffern (Ortscode, optional dreistelliger Filialcode). Leerzeichen werden entfernt und Kleinbuchstaben normalisiert. Eine formal gültige BIC, die nicht zur IBAN passt, ist kein Request-Fehler, sondern liefert HTTP 200 mit status: 2.
Betroffenes Feld: bic
{
"error": {
"http_status": 400,
"code": "invalid_bic",
"message": "The BIC is invalid or has an incorrect format",
"field": "bic"
}
}Ungültige Kontonummer
Die Kontonummer wurde nicht angegeben, ist gleich null oder enthält nicht-numerische Zeichen.
Betroffenes Feld: kontonummer
{
"error": {
"http_status": 400,
"code": "invalid_kontonummer",
"message": "Account number is missing or contains invalid characters",
"field": "kontonummer"
}
}Ungültige Bankleitzahl
Die Bankleitzahl wurde nicht angegeben oder enthält nicht-numerische Zeichen. Eine gültige deutsche BLZ ist 8-stellig und rein numerisch.
Betroffenes Feld: bankleitzahl
{
"error": {
"http_status": 400,
"code": "invalid_blz",
"message": "Bank code (BLZ) is missing or contains invalid characters",
"field": "bankleitzahl"
}
}Ungültige Batch-Größe
Das Array ibans im POST-Body ist leer oder enthält mehr als 500 Einträge. Pro Anfrage sind 1 bis 500 IBANs erlaubt.
{
"error": {
"http_status": 400,
"code": "batch_size_invalid",
"message": "Batch must contain 1 to 500 IBANs"
}
}Ungültiges Batch-Format
Das Feld ibans im POST-Body ist vorhanden, aber kein Array (z. B. ein einzelner String statt einer Liste). Für eine Einzelprüfung stattdessen das Feld iban verwenden, für eine Batch-Prüfung ibans als Array mit 1 bis 500 Einträgen.
Betroffenes Feld: ibans
{
"error": {
"http_status": 400,
"code": "invalid_batch_ibans",
"message": "The 'ibans' field must be an array of IBANs",
"field": "ibans"
}
}Widersprüchliche IBAN-Felder
Der POST-Body an /v1/iban enthält gleichzeitig iban (Einzelprüfung) und ibans (Batch-Prüfung). Nur eines der beiden Felder pro Request verwenden.
{
"error": {
"http_status": 400,
"code": "conflicting_iban_fields",
"message": "iban and ibans must not be sent at the same time"
}
}Falscher Content-Type
POST-Requests an /v1/kto, /v1/iban oder /v1/search ohne Pfad-Parameter erfordern Content-Type: application/json. Andere Content-Types (z. B. application/x-www-form-urlencoded) werden nicht unterstützt.
{
"error": {
"http_status": 400,
"code": "invalid_content_type",
"message": "POST requests to this endpoint require Content-Type: application/json"
}
}Request-Body zu groß
Der Request-Body überschreitet das Limit von 128 KB.
{
"error": {
"http_status": 413,
"code": "payload_too_large",
"message": "The request body is too large (max. 128 KB)"
}
}Ungültige PLZ (Banksuche)
Der Parameter zip der Banksuche (/v1/search) enthält nicht-numerische Zeichen.
Betroffenes Feld: zip
{
"error": {
"http_status": 400,
"code": "invalid_zip",
"message": "Postal code must contain digits only for search",
"field": "zip"
}
}Ungültiger JSON-Request-Body
Der Request-Body ist gültiges JSON, aber kein Objekt (z. B. ein Array) statt {...}. Syntaktisch defektes JSON liefert stattdessen invalid_request. Ein leerer Body löst diesen Fehler nicht aus, sondern führt zum passenden Feldfehler (z. B. invalid_kontonummer).
{
"error": {
"http_status": 400,
"code": "invalid_json",
"message": "The request body is not a valid JSON object"
}
}Kein Suchkriterium angegeben
Die Banksuche (/v1/search) wurde ohne jedes Suchfeld aufgerufen. Mindestens eines der Felder name, location, zip oder bankleitzahl muss belegt sein.
{
"error": {
"http_status": 400,
"code": "missing_search_criteria",
"message": "At least one of the fields name, location, zip or bankleitzahl must be provided"
}
}Ungültiger Parameter max
Der Parameter max der Banksuche ist gesetzt, aber nicht rein numerisch oder liegt außerhalb des zulässigen Bereichs 1–50. Fehlt max oder ist er leer, greift stattdessen der Default 10 – das ist kein Fehler.
Betroffenes Feld: max
{
"error": {
"http_status": 400,
"code": "invalid_max",
"message": "The max parameter must be between 1 and 50",
"field": "max"
}
}Ungültiger Parameter sepa
Der Parameter sepa ist gesetzt, aber weder 0 noch 1. Fehlt sepa, greift stattdessen der Default 0 – das ist kein Fehler.
Betroffenes Feld: sepa
{
"error": {
"http_status": 400,
"code": "invalid_sepa",
"message": "The sepa parameter must be 0 or 1",
"field": "sepa"
}
}Ungültige Anfrage
Allgemeiner Fehlercode für zwei Fälle mit identischem Antwortformat, aber unterschiedlichem Meldungstext:
1. Pfad passt zu keinem bekannten Endpunkt-Muster – z. B. /v1/kto/… oder /v1/iban/… mit zusätzlichen oder fehlenden Segmenten. Wird nur verwendet, wenn kein spezifischerer Code (z. B. invalid_kontonummer, invalid_iban) zutrifft.
{
"error": {
"http_status": 400,
"code": "invalid_request",
"message": "Invalid request"
}
}2. Request-Body ist kein gültiges JSON (syntaktisch defekt oder abgeschnitten). Zu unterscheiden von invalid_json, das nur bei syntaktisch gültigem JSON greift, das kein Objekt ist.
{
"error": {
"http_status": 400,
"code": "invalid_request",
"message": "The request could not be processed. Most common cause: the request body is not valid JSON."
}
}Methodenfehler
Methode nicht erlaubt
Die verwendete HTTP-Methode ist für diesen Endpunkt nicht zulässig. Verwenden Sie die im Allow-Response-Header angegebene Methode.
Betroffen: alle Endpunkte — z. B. POST auf einen GET-only Endpunkt wie GET /v1/kto/{kontonummer}/{bankleitzahl}.
{
"error": {
"http_status": 405,
"code": "method_not_allowed",
"message": "Method not allowed. Allowed: GET"
}
}Sonstige HTTP-Fehler
Diese Codes stammen von der Webserver-Ebene, nicht aus der Anwendungslogik. Das Antwortformat ist dasselbe wie bei allen anderen Fehlern.
Zugriff verweigert
Der Zugriff auf diese Ressource ist nicht erlaubt.
{
"error": {
"http_status": 403,
"code": "forbidden",
"message": "Access to this resource is not allowed."
}
}Nicht gefunden
Die angeforderte Ressource existiert nicht.
{
"error": {
"http_status": 404,
"code": "not_found",
"message": "The requested resource was not found."
}
}Unerwarteter Serverfehler
Ein unerwarteter Serverfehler, z. B. bei einem unvollständig übertragenen Request-Body. Die Anfrage kann in der Regel unverändert erneut versucht werden. Tritt der Fehler dauerhaft auf, kontaktieren Sie den Support.
{
"error": {
"http_status": 500,
"code": "internal_error",
"message": "An unexpected server error occurred."
}
}Systemfehler
Interner Verarbeitungsfehler
Die Prüfung konnte serverseitig nicht durchgeführt werden. Die Anfrage war syntaktisch korrekt — bitte wiederholen Sie den Request. Hält der Fehler an, wenden Sie sich an den Support.
{
"error": {
"http_status": 500,
"code": "ckonto_failed",
"message": "cKonto could not be executed"
}
}Server ausgelastet
Alle Verarbeitungsplätze für Prüfungen sind im Moment belegt (Obergrenze gleichzeitiger Prüfungen erreicht). Die Anfrage wurde nicht verarbeitet und nicht gezählt. Senden Sie sie nach der im Response-Header Retry-After genannten Wartezeit (Sekunden) unverändert erneut.
Retry-After: 2
{
"error": {
"http_status": 503,
"code": "server_busy",
"message": "Server busy, please retry"
}
}Serverkonfiguration unvollständig
Die API konnte ihre Serverkonfiguration nicht laden. Das liegt nicht an Ihrer Anfrage; ein Wiederholen des Requests ändert daran nichts. Kontaktieren Sie den Support, falls dieser Fehler anhält.
{
"error": {
"http_status": 500,
"code": "configuration_error",
"message": "Server configuration incomplete"
}
}