Alle Fehler werden als JSON-Objekt mit dem Schlüssel error zurückgegeben. Der Response-Body hat immer folgende Struktur:

{
  "error": {
    "http_status": 401,
    "code": "invalid_key",
    "message": "Der Zugriffsschlüssel ist nicht gültig",
    "field": "..."        // optional – nur bei Eingabefehlern
  }
}

Einzelne Fehlercodes können direkt verlinkt werden, z. B. /api/docs/errors#invalid_key.

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": "Der Zugriffsschlüssel ist nicht gültig"
  }
}

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": "Die IBAN ist ungueltig oder hat ein falsches Format",
    "field": "iban"
  }
}

Ungültige BIC

Die übergebene BIC ist länger als 11 Zeichen oder enthält ungültige Zeichen. Gültig sind ausschließlich Buchstaben und Ziffern.

Betroffenes Feld: bic

{
  "error": {
    "http_status": 400,
    "code": "invalid_bic",
    "message": "Die BIC ist ungueltig oder hat ein falsches 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": "Kontonummer wurde nicht angegeben oder enthaelt ungueltige Zeichen",
    "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": "Bankleitzahl wurde nicht angegeben oder enthaelt ungueltige Zeichen",
    "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 muss 1 bis 500 IBANs enthalten"
  }
}

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": "Methode nicht erlaubt. Erlaubt: GET"
  }
}

Interner Verarbeitungsfehler

Das cKonto-Backend konnte nicht ausgeführt werden oder hat keine Antwort geliefert. 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 konnte nicht ausgefuehrt werden"
  }
}