Fehler, Doppelanträge und Wartung

Zwei Arten von Fehlern

Vor dem Versand prüft die Schnittstelle, was sich ohne das KBA prüfen lässt: Pflichtfelder, Wertelisten, Formate von FIN, Kennzeichen, Sicherheitscodes, eVB, IBAN und Großkunden-ID, die Prüfziffer der ZB II, Vollmacht und Halterdaten. Ein Verstoß kommt sofort als HTTP-Fehler zurück — es wird kein Vorgang angelegt und nichts gesendet. Die Prüfung läuft in Stufen: Fehlt ein Grundbaustein, etwa die Kennzeichenteile oder vehicleHolder.address, nennt die Meldung nur ihn. Erst danach sammelt sie weitere fehlende Angaben, eine je Zeile. Rechnen Sie damit, dass nach einer Korrektur eine weitere Meldung folgt.

Nach dem Versand entscheidet das KBA. Eine Abweisung oder Ablehnung kommt nicht als HTTP-Fehler, sondern als Zustand des Vorgangs: Webhook-Ereignis mit status FAILED bzw. REJECTED…, die Meldungen des KBA in messages samt Quittungscode. Was ein Code bedeutet, steht unter Quittungscodes.

Scheitert schon der Versand, gibt es keinen Quittungscode: keine Verbindung, Zeitüberschreitung, vom KBA abgelehnte Anmeldung oder eine Antwort ohne lesbare Quittung. Der Vorgang endet als fehlgeschlagen. Das Webhook-Ereignis kommt mit status FAILED, aber ohne messages und ohne retryable. Die Vorgangsauskunft nennt den technischen Grund als Text in messages[].code. Nach einer abgelehnten Anmeldung ist der Antrag nicht beim KBA angekommen. Nach einer Zeitüberschreitung oder abgebrochenen Verbindung ist offen, ob er angekommen ist; nach einer unlesbaren Antwort ist offen, ob das KBA ihn angenommen hat. Klären Sie diese beiden Fälle mit der order.id beim Support, bevor Sie erneut senden.

Fehlerformat

{
  "error": "Kein Vollmachtsvorgang mit der Nummer 7. (TraceId: c41f7e02-9a3b-4d6c-8e15-b27d0a9f6c33)",
  "traceId": "c41f7e02-9a3b-4d6c-8e15-b27d0a9f6c33"
}

traceId steht auch in der Kopfzeile X-Trace-Id — nennen Sie sie beim Support; dort steht auch, wie Sie ihn ohne Anmeldung erreichen und was eine Anfrage sonst braucht. Einzelheiten unter Übersicht.

Dasselbe Format tragen auch die Fehler, die noch vor dem Routing entstehen: eine zu lange Adresse ergibt 414 mit {error, traceId} und X-Trace-Id, ohne den angefragten Pfad zu spiegeln. Eine von Ihnen mitgegebene X-Trace-Id wird auch dort übernommen.

Eine Ausnahme bleibt. Zu große Kopfzeilen (431) und eine kaputte Anfragezeile (400) beantwortet der HTTP-Server von Node, bevor es eine Anfrage im Sinne der Schnittstelle gibt. Diese beiden Antworten tragen weder das Format noch die Kopfzeile.

Statuscodes der Anträge

Bei 401, 403, 404, 409 und 503 hilft ein unverändertes Wiederholen nicht.

Die Anmeldesperre (503). Lehnt das KBA die Anmeldung eines GKS-Zugangs ab — etwa weil das Kennungspasswort abgelaufen ist —, hält die Schnittstelle alle Aufrufe dieser Kennung an; sonst wäre die Kennung nach drei Fehlversuchen beim KBA gesperrt. Aufrufe, die danach eintreffen, bekommen 503; für sie wird kein Vorgang angelegt und nichts gesendet. Anträge, die schon angenommen waren, enden dagegen als fehlgeschlagen: der, dessen Versand die Sperre auslöst, und alle, die zu dieser Zeit noch auf ihren Versand warten. Die anderen Zugänge senden weiter. Die Sperre gibt der Betrieb frei, nachdem die Ursache behoben ist.

Doppelantragsschutz

Bricht Ihre Verbindung ab, bevor die Antwort ankommt, dürfen Sie den Antrag unverändert wiederholen. Er gilt als Wiederholungsversuch, wenn alles zutrifft:

• derselbe Mandant,
• dieselbe externalOrderId,
• dieselbe FIN (Groß- und Kleinschreibung spielt keine Rolle),
• derselbe Geschäftsvorfall, also derselbe Endpunkt,
• innerhalb von 15 Minuten nach dem ersten Antrag,
• und der erste ist nicht fehlgeschlagen.

Dann geht nichts erneut an das KBA, und die Antwort nennt den bestehenden Vorgang: HTTP 200 mit derselben order.id. Läuft der Versand des ersten Antrags noch, löst ein erkannter Wiederholungsversuch kein Webhook-Ereignis aus; das Ergebnis meldet das Ereignis des ersten Antrags. Ist der erste Antrag schon quittiert, meldet die Wiederholung dessen Stand in einem weiteren Ereignis erneut, mit denselben Meldungen. Ohne externalOrderId greift der Schutz nicht.

Unverändert heißt: dieselben Felder mit denselben Werten. Die Reihenfolge der Schlüssel und Leerraum im JSON spielen keine Rolle, die Reihenfolge der Einträge in Listen schon. FIN und Kennzeichenteile werden vor dem Vergleich in der Schreibweise vereinheitlicht. Eingebettete Dokumente (documentBase64, fileBase64, contentBase64) gehen über ihren Fingerabdruck in den Vergleich ein: Dasselbe Dokument gilt als Wiederholung, ein anderes als andere Daten.

{
  "externalOrderId": "auftrag-0815",
  "email": "kunde@example.de",
  "customization": {
    "licensePlateNumberComponents": { "city": "HN", "middle": "LL", "end": "2418" },
    "frontLicensePlateSecurityCode": "Vbg",
    "rearLicensePlateSecurityCode": "K7m",
    "vehicleIdentificationNumber": "WBA65432113218654",
    "vehicleRegistrationCertificateSecurityCode": "8407251",
    "licensePlateReservationIncluded": false
  }
}

Dieselbe Referenz und FIN mit anderen Daten — hier mit Reservierung — ist kein Wiederholungsversuch. Die Schnittstelle antwortet mit 409 und ändert nichts:

{
  "externalOrderId": "auftrag-0815",
  "email": "kunde@example.de",
  "customization": {
    "licensePlateNumberComponents": { "city": "HN", "middle": "LL", "end": "2418" },
    "frontLicensePlateSecurityCode": "Vbg",
    "rearLicensePlateSecurityCode": "K7m",
    "vehicleIdentificationNumber": "WBA65432113218654",
    "vehicleRegistrationCertificateSecurityCode": "8407251",
    "licensePlateReservationIncluded": true
  }
}

{
  "error": "Unter der Referenz \"auftrag-0815\" und der FIN WBA65432113218654 liegt bereits Vorgang 1 — mit anderen Daten. Ihre Angaben weichen davon ab und wurden NICHT übernommen. Wollen Sie einen weiteren Antrag stellen, vergeben Sie eine eigene Referenz; wollen Sie den bestehenden berichtigen, korrigieren Sie ihn über den Vorgang. (TraceId: 7b90c3e4-2f1a-4d85-a6c7-3e8d1b5f09a2)",
  "traceId": "7b90c3e4-2f1a-4d85-a6c7-3e8d1b5f09a2"
}

Für POST /powerOfAttorneys gilt ein eigener Schutz ohne Frist, siehe Wiederholen ohne zweiten Vorgang.

Folgerungen für Ihren Client:

• Vergeben Sie je Auftrag eine eigene externalOrderId und schicken Sie sie bei einer Wiederholung unverändert mit.
• Dieselbe Referenz an einem anderen Endpunkt — NZ statt TZ, WG statt WZ — ist ein neuer Antrag samt Gebühr. Einen falsch gewählten Endpunkt berichtigt kein erneutes Senden.
• Nach mehr als 15 Minuten oder nach einem fehlgeschlagen geht derselbe Antrag wieder als neuer hinaus.
• Eine korrigierte Vollmacht unter derselben Referenz und FIN ergibt innerhalb von 15 Minuten 409, nicht den bestehenden Vorgang.

Antwort sofort, Versand im Hintergrund

Die Antwort auf einen Antrag kommt, sobald der Vorgang angelegt ist — bevor das KBA geantwortet hat. Der Vorgang steht dann auf angelegt, applicationId ist noch leer. Der Versand an das KBA und das Auswerten der Quittung laufen im Hintergrund; das Ergebnis meldet das erste Webhook-Ereignis.

Bricht die Instanz zwischen Antwort und Versand ab, meldet sie beim nächsten Start die Vorgänge, die zu diesem Zeitpunkt schon länger als 15 Minuten angelegt und nie gesendet sind, als fehlgeschlagen mit Code 99995 und retryable: true. Reichen Sie diese neu ein. Einen regelmäßigen Lauf gibt es nicht: Ein Vorgang, der beim Neustart jünger war, bleibt ohne Ereignis auf angelegt, bis die Instanz erneut startet. Steht ein Vorgang länger als 15 Minuten auf angelegt und hat keine applicationId, melden Sie ihn mit order.id beim Support.

Vorübergehende Störungen

Einige Quittungscodes heißen „gerade nicht möglich" statt „abgelehnt", etwa 00024, 07078 (Zuständigkeitsfinder antwortet nicht), 07082 (i-Kfz-Portal nicht verfügbar), 07086 (Vorgang kann im Moment nicht durchgeführt werden) und 99995. Ein so gescheiterter Vorgang trägt retryable: true. Derselbe Antrag hat später Aussicht auf Erfolg — aber ob er beim KBA angekommen ist, sagt eine Fehlerquittung nicht sicher. Prüfen Sie vor einem automatischen erneuten Senden die Vorgangsauskunft, sonst riskieren Sie eine doppelte Zulassung.

Wartungsfenster des KBA

Außerhalb von Notfallwartungen wartet das KBA zu festen Zeiten (deutsche Ortszeit):

In diesen Zeiten sind Störungen zu erwarten. Die Schnittstelle nimmt Anträge weiterhin an und sendet sie; scheitert ein Versand, meldet sie das als Zustand des Vorgangs. Angekündigte Sonderwartungen des KBA sind hier nicht abgebildet. Störungen und Wartungen, die der Betrieb meldet, liefert GET /serviceStatus; die festen Fenster oben erscheinen dort nicht.