Schnittstellenfehler im Betrieb: Überwachen, wiederholen, abgleichen

Zwischen der Annahme einer Nachricht und ihrer Verbuchung im Zielsystem liegt eine Lücke, die kein Protokolleintrag von selbst schließt. Der Statuscode einer Antwort beschreibt das Ergebnis eines Aufrufs; ob er zugleich die Verbuchung beim Empfänger belegt, hängt vom Statuscode und von der vereinbarten Semantik ab. Ein Verlust wird erst sichtbar, wenn beide Seiten dieselbe Größe zählen.

Was Sie vorab brauchen

• Zugriff auf Ausgangs- und Eingangsprotokoll beider Systeme, mindestens für die letzten 30 Tage.
• Eine Zählgröße je Richtung: Anzahl der Sätze je Tag, Schnittstelle und Nachrichtenart.
• Ein Merkmal, das eine Nachricht eindeutig kennzeichnet und vom Sender je Nachricht einmal vergeben wird.
• Falls der Aufruf nicht ohnehin nachweislich idempotent ist (RFC 9110, Abschnitt 9.2.2): eine mit dem Partner vereinbarte und beim Empfänger umgesetzte Dublettensperre mit Feldname, Aufbewahrungsdauer und dem Verhalten bei gleichem Schlüssel mit anderer Nutzlast.
• Eine schriftliche Wiederholungsregel: welche Antwort wiederholt wird, wie oft, mit welcher Wartezeit, unter welcher Sicherheitsbedingung, und wer danach übernimmt.
• Zeitsynchronisation beider Systeme und ein einheitliches Zeitformat in den Protokollen.

RFC 9110 (HTTP Semantics, STD 97, Juni 2022) beschreibt Statuscodes, die Wiederholbarkeit der Methoden und das Feld Retry-After; verbindlich wird er über die Vereinbarung mit dem Partner, nicht von Gesetzes wegen. Für die Protokollierung nennt der BSI-Baustein OPS.1.1.5 des IT-Grundschutz-Kompendiums (Edition 2023) Anforderungen, die nur binden, wo Gesetz, Aufsicht oder Vertrag darauf verweisen.

Woran Sie einen stillen Verlust erkennen

Die Klasse 2xx bedeutet nach RFC 9110, Abschnitt 15.3, dass die Anfrage erfolgreich empfangen, verstanden und angenommen wurde. Innerhalb der Klasse ist das Ergebnis unterschiedlich genau benannt: 200 sagt, dass die Anfrage gelungen ist (Abschnitt 15.3.1), 201, dass eine neue Ressource erzeugt wurde (Abschnitt 15.3.2); beide beziehen sich auf den Aufruf, nicht auf eine danach noch laufende Verarbeitung. Nur 202 Accepted sagt ausdrücklich, dass die Anfrage zur Verarbeitung angenommen und noch nicht abgeschlossen ist (Abschnitt 15.3.3). Legt die Gegenseite die Arbeit in eine eigene Warteschlange und antwortet mit 202, sagt diese Annahme nichts über die Verbuchung; wer nur Erfolgsmeldungen zählt, sieht keinen Verlust, solange das Zielsystem nicht verbucht.

Die Tabelle ordnet jeder Antwortgruppe zu, was sie für eine Wiederholung bedeutet; am Statuscode muss ein Client die Klasse verstehen, eine unbekannte Nummer behandelt er wie die x00-Nummer ihrer Klasse (Abschnitt 15).

Antwort	Bedeutung nach RFC 9110	Für die Wiederholung
2xx ohne 202	Anfrage erfolgreich empfangen, verstanden und angenommen (15.3); 200 nennt die Anfrage gelungen (15.3.1), 201 die erzeugte Ressource (15.3.2)	Nicht wiederholen; 200 nennt den gelungenen Aufruf, 201 die erzeugte Ressource, eine noch ausstehende Verarbeitung bestätigen beide nicht
202	Angenommen, Verarbeitung nicht abgeschlossen (15.3.3)	Nicht wiederholen; den Stand der Verarbeitung abfragen
400, 401, 403, 405, 415	Anfrage passt nicht: Syntax, Zugang oder Format	Nicht wiederholen; Inhalt, Feldzuordnung, Zugangsdaten oder Rechte klären
422	Inhalt verstanden, aber nicht verarbeitbar (15.5.21); kann auch ein wiederverwendeter Schlüssel mit anderer Nutzlast sein (Entwurf, 2.7)	Nicht wiederholen; Inhalt oder Schlüssel klären
408	Anfrage nicht vollständig erhalten (15.5.9)	Wiederholen ist zulässig; bei nicht idempotenter Methode gilt die Bedingung unten
409	Konflikt mit dem Zustand des Ziels (15.5.10); der Entwurf nutzt ihn für eine noch laufende erste Anfrage (2.7)	Nicht blind wiederholen; prüfen, ob der Satz schon verbucht ist oder noch läuft
429	Grenze für Anfragen erreicht (RFC 6585, Abschnitt 4)	Nach der angegebenen Wartezeit erneut senden, sofern der Aufruf sicher wiederholbar ist
500, 502, 503	Fehler oder Überlast auf der Gegenseite (15.6.1 bis 15.6.4)	Erneut versuchen nur bei sicher wiederholbarem Aufruf; 503 darf ein Retry-After mitsenden (15.6.4, 10.2.3)
504	Ein Gateway hat keine rechtzeitige Antwort erhalten (15.6.5)	Kein Beleg, dass die Anfrage unverarbeitet blieb; ohne Nachweis nicht automatisch wiederholen

Ob eine Wiederholung sicher ist, sagt der Statuscode nicht von selbst. Nach RFC 9110, Abschnitt 9.2.2, soll ein Client eine Anfrage mit nicht idempotenter Methode nur automatisch wiederholen, wenn er nachweisen kann, dass ihre Semantik doch idempotent ist oder dass die erste Anfrage nie angewendet wurde. Eine 5xx-Antwort belegt das nicht: 500 nennt eine unerwartete Bedingung beim Server, 502 eine ungültige Antwort eines vorgelagerten Servers, 503 eine vorübergehende Überlast, 504 eine ausgebliebene rechtzeitige Antwort (Abschnitte 15.6.1 bis 15.6.5); in jedem dieser Fälle kann die erste Anfrage angewendet worden sein. Ohne diesen Nachweis gehört der Satz in die Fehlerwarteschlange, und ein Mensch entscheidet.

Einen stillen Verlust zeigt keine dieser Antworten an. Zwei Beobachtungen weisen auf ihn hin:

• Der Zeitstempel der jüngsten erfolgreich verbuchten Nachricht bleibt stehen, während der Sender weiter abgibt. Der BSI-Baustein OPS.1.1.5 nennt den unbemerkt gebliebenen Ausfall einer Datenquelle als Gefährdung (Abschnitt 2.7).
• Die Warteschlange des Empfängers wächst, während die Antworten Erfolg melden: angenommen, aber nicht ausgeführt.

Checkliste: Warteschlange, Wiederholungsregeln, Schlüssel, Tagesabgleich

Die vier Teile gehören zusammen.

Fehlerwarteschlange

• Jede nicht verbuchte Nachricht bleibt mit Nutzlast, Zeitstempel, Statuscode und Fehlertext liegen; nichts wird automatisch verworfen.
• “Erledigt” setzt die Bestätigung des Zielsystems voraus, nicht die Annahme der Nachricht.
• Fehlerantworten maschinenlesbar halten: RFC 9457 beschreibt type, status, title, detail und instance; der type-URI benennt die Fehlerart. Auch dieses Format bindet über Vereinbarung.
• Je Fehlerart in der Warteschlange eine zuständige Person und eine Frist.

Wiederholungsregeln

Fall	Automatische Wiederholung	Beispiel für die Wartezeit
408 oder 5xx ohne Retry-After	ja, begrenzt, und nur bei sicher wiederholbarem Aufruf	Versuche nach 1, 5 und 15 Minuten, danach Handarbeit
429 oder 503 mit Retry-After	ja, nach dem Wert der Antwort, sofern der Aufruf sicher wiederholbar ist	mindestens so lange wie angegeben
409	nein	prüfen, ob der Satz schon verbucht ist, dann von Hand erneut senden
andere 4xx	nein	Fehler beheben; ohne Nutzlaständerung derselbe Schlüssel, sonst eine neue Nachricht mit eigenem Schlüssel
202	nein	Stand der Verarbeitung abfragen, zum Beispiel nach 15 Minuten

Die Wartezeiten sind Beispielwerte dieser Redaktion und an die Taktzeit der Schnittstelle anzupassen. Jede Regel braucht die Höchstzahl der Versuche, die Gesamtdauer bis zur Übernahme durch einen Menschen und ein Ende der Kette – und die Bedingung, unter der eine automatische Wiederholung überhaupt sicher ist: eine nachweislich idempotente Methode oder die Bestätigung des Empfängers, dass die erste Anfrage nie angewendet wurde (RFC 9110, Abschnitt 9.2.2). Ein Statuscode aus der 5xx-Klasse, insbesondere ein 504 nach einem Gateway-Zeitablauf (Abschnitt 15.6.5), ist kein solcher Nachweis: Der erste Aufruf kann angewendet worden sein, während die Antwort verloren ging. Ohne Nachweis wandert der Satz sofort in die Fehlerwarteschlange.

Schlüssel je Nachricht

• Nach RFC 9110, Abschnitt 9.2.2, sind PUT, DELETE und die lesenden Methoden idempotent: Mehrere gleiche Anfragen wirken wie eine, und eine solche Anfrage darf nach einem Verbindungsabbruch automatisch wiederholt werden.
• Für POST und PATCH gilt das nicht: Eine nicht idempotente Anfrage soll ein Client nicht automatisch wiederholen, außer er kann feststellen, dass ihre Semantik doch idempotent ist oder dass sie nie angewendet wurde (Abschnitt 9.2.2). Ein Schlüssel ist dieser Nachweis nicht von sich aus; er wird erst einer, wenn der Empfänger ihn speichert, zur Nachricht sucht und die Dublette verwirft.
• Den Feldnamen Idempotency-Key beschreibt ein Internet-Entwurf der IETF, der am 18. April 2026 abgelaufen und kein veröffentlichter Standard ist (geprüft am 14. Oktober 2026). Der Entwurf verlangt einen eindeutigen Schlüssel je Nachricht, der nicht mit anderer Nutzlast wiederverwendet werden darf (Abschnitt 2.2), lässt eine Ablauffrist des Schlüssels zu (Abschnitt 2.3) und sagt für den Client ausdrücklich, dass dieser ohne Vorwissen nicht annehmen kann, der Server beachte den Schlüssel (Abschnitt 2.5.1). Vereinbaren Sie Feldname, Ort des Feldes, Aufbewahrungsdauer und das Verhalten bei gleichem Schlüssel mit anderer Nutzlast schriftlich.
• Kommt dieselbe Nachricht mit demselben Schlüssel erneut an, verhindert eine zweite Buchung nur eine dieser beiden Bedingungen: Der Aufruf ist nach seiner Semantik idempotent, auch wenn die Methode POST lautet (RFC 9110, Abschnitt 9.2.2), oder der Empfänger setzt die Dublettensperre durch – er speichert den Schlüssel, ordnet ihn der Nachricht zu und weist die zweite Sendung ab. Ist ein Buchungsaufruf nicht idempotent und fehlt die Dublettensperre, kann eine Wiederholung eine zweite Buchung erzeugen; ob die erneute Anfrage überhaupt durchgeht, ist damit nicht gesagt.

Tagesabgleich

• Eine Zeile je Schnittstelle, Richtung und Tag: gesendete Sätze, verbuchte Sätze, Differenz, beide Wertsummen, Zeitstempel der jüngsten erfolgreichen Nachricht.
• Beide Größen vergleichen: Über die Anzahl fallen fehlende Sätze auf, über die Wertsumme doppelte oder falsch bewertete; beides ist ein Verdacht, keine Ursache.
• Jede Abweichung, aber auch gleiche Summen bei unklarer Lage am Tag der Entstehung klären, sonst fehlt später der Beleg für die Ursache. Welcher Satz fehlt oder doppelt vorliegt, zeigt erst der Abgleich der Sendeschlüssel: Ein Verlust und eine Dublette können sich in Anzahl und Wert gegenseitig aufheben (Beispielrechnung: zwei gesendete Aufträge zu je 100 Euro, einer verloren und der andere doppelt verbucht, ergeben dieselbe Anzahl und dieselbe Summe).
• Zeitstempel mit Zeitzonenversatz schreiben (RFC 3339, Abschnitt 5.6), damit sich Sätze über Systemgrenzen zuordnen lassen.

Beispielalarme

Beobachtung	Beispielwert für die Meldung
Neue Nachrichten in der Fehlerwarteschlange	mehr als 10 innerhalb von 60 Minuten
Alter der ältesten offenen Nachricht	mehr als 2 Stunden
Zeitstempel der jüngsten erfolgreichen Nachricht	älter als die dreifache Taktzeit, mindestens 60 Minuten
Antworten mit 429	mehr als 5 Prozent der Aufrufe einer Stunde
Wiederholungen	drei Versuche innerhalb der Regel ohne Erfolg
Tagesabgleich	jede Differenz ungleich null und jede ungeklärte Lage bei gleichen Summen

Die Werte sind Beispielwerte dieser Redaktion; zu jeder Zeile gehören eine zuständige Person, eine Vertretung und eine Frist.

Schritt für Schritt: Fehler bemerken und aufarbeiten

Schritt 1: Sendeschlüssel festlegen

Legen Sie mit dem Partner fest, welches Feld den Schlüssel trägt und wie er gebildet wird: aus Merkmalen des Geschäftsvorfalls, nicht aus der Uhrzeit. Füllen Sie das Feld in jeder Nachricht. Halten Sie schriftlich fest, wie der Empfänger denselben Schlüssel ein zweites Mal behandelt, wie lange er ihn aufbewahrt und was er bei gleichem Schlüssel mit anderer Nutzlast antwortet. Ende: Zwei Sendungen desselben Vorgangs tragen denselben Wert, zwei verschiedene Vorgänge verschiedene Werte, und der Empfänger hat die Dublettensperre bestätigt.

Schritt 2: Fehlerwarteschlange anlegen

Richten Sie einen Ablageort ein, in den jede nicht verbuchte Nachricht mit Nutzlast, Zeitstempel, Statuscode und Fehlertext wandert. Verhindern Sie, dass das sendende Programm einen Fehler nur protokolliert und die Nachricht verliert. Ende: Eine absichtlich fehlerhafte Testnachricht liegt sichtbar in der Warteschlange.

Schritt 3: Wiederholungsregeln eintragen

Hinterlegen Sie je Antwortgruppe das Verhalten aus der Tabelle: wiederholen oder nicht, mit welchen Wartezeiten, wie oft. Tragen Sie für jede automatische Wiederholung die Sicherheitsbedingung ein: Der Aufruf ist idempotent, oder der Empfänger hat bestätigt, dass die erste Anfrage nie angewendet wurde. Lesen Sie ein mitgesendetes Retry-After aus und warten Sie mindestens diesen Wert. Setzen Sie eine Obergrenze. Ende: Nach dem letzten Versuch wartet die Nachricht auf einen Menschen, und die Kette endet.

Schritt 4: Tagesabgleich zählen

Bauen Sie die Zählung auf beiden Seiten auf und tragen Sie beide Zahlen in dieselbe Zeile ein. Zählen Sie Sätze, keine Dateien und keine Aufrufe. Ende: Der Abgleich zeigt am nächsten Morgen die Zeile des Vortags mit beiden Zahlen und der Differenz.

Schritt 5: Alarmgrenzen setzen

Übernehmen Sie die Beispielalarme als Startpunkt und ordnen Sie jeder Meldung eine zuständige Person, eine Vertretung und eine Frist zu. Lösen Sie die Meldungen einmal in einer Testumgebung aus. Ende: Ein unterbrochener Aufruf erzeugt innerhalb der Frist eine Meldung an eine bekannte Adresse.

Schritt 6: Protokollierung selbst prüfen

Kontrollieren Sie in festen Abständen, dass Protokolle geschrieben werden und die Zeitangaben zusammenpassen. Der BSI-Baustein OPS.1.1.5 nennt als Anforderungen eine stichprobenartige Prüfung der Protokollierung (A3), einheitliche Zeitformate (A4) und getrennte Rechte für aufgezeichnete Daten (A10). Ende: Für den Monat liegt der Nachweis der Kontrolle vor.

So prüfen Sie das Ergebnis

1. Dieselbe Nachricht zweimal mit demselben Schlüssel senden. Ergebnis: eine Buchung, sofern der Empfänger die Dublettensperre tatsächlich umgesetzt hat oder der Aufruf nach seiner Semantik idempotent ist (RFC 9110, Abschnitt 9.2.2).
2. Den ersten Aufruf unbeantwortet lassen, etwa durch Abbruch der Verbindung, und die Wiederholung anstoßen. Ergebnis: Entweder ist der Aufruf sicher wiederholbar oder die Nachricht landet mit ihrem Schlüssel in der Fehlerwarteschlange – nicht in einem zweiten Verbuchungsversuch.
3. Die Gegenseite in einer Testumgebung anhalten. Ergebnis: Die Warteschlange füllt sich, die Meldung kommt innerhalb der Frist.
4. Einen Satz aus dem Abgleich weglassen. Ergebnis: Die Anzahl differiert um eins, der Zeitstempel grenzt das Zeitfenster ein.
5. Die Systemzeit eines Testsystems verstellen. Ergebnis: Der Abgleich ordnet Sätze falsch zu; die Zeitsynchronisation gehört dazu.

Wenn etwas nicht klappt

Symptom	Ursache	Abhilfe
Warteschlange ist leer, aber Aufträge fehlen	Die Gegenseite antwortet mit Erfolg und scheitert erst bei der Verarbeitung	Den Stand der Verarbeitung abfragen und jede Buchung bestätigen lassen
Derselbe Auftrag steht zweimal im Zielsystem	Wiederholung nach Zeitablauf ohne Schlüssel	Schlüssel je Nachricht einführen und die Wiederholung daran binden
Die Meldung kommt, aber niemand reagiert	Keine Zuständigkeit und keine Frist je Alarmzeile	Zuständigkeit, Vertretung und Frist festlegen
Nach einem 5xx wird derselbe Satz doppelt verbucht	Wiederholung nach 500 oder 504 ohne Nachweis der Nichtverarbeitung	Automatische Wiederholung auf idempotente Aufrufe und bestätigte Nichtverarbeitung begrenzen, sonst den Satz in die Warteschlange geben
Eine 400er-Antwort wird immer wieder gesendet	Die Regel wiederholt jede Antwort	Wiederholung auf 408, 429 und 5xx begrenzen und je Fall die Sicherheitsbedingung prüfen

Wann Sie Hilfe holen sollten

Ziehen Sie die Softwarebetreuung oder den Anbieter hinzu, wenn die Gegenseite keinen Stand der Verarbeitung liefert, wenn sie denselben Schlüssel nicht durchsetzt, wenn derselbe Satz trotz Schlüssel zweimal verbucht wird, wenn Antworten mit 429 im Dauerbetrieb auftreten oder wenn der Tagesabgleich ohne erkennbare Ursache differiert.

Welche Testarten zu Fehler-, Mengen- und Wiederholungsfall gehören, ordnet Schnittstellen vor dem Start testen ein. Welche Felder eine Anbindung tragen muss, beschreibt CSV-Austausch mit dem ERP, und welche Fähigkeiten eine Anbindung mitbringt, prüfen Sie mit offene ERP-Schnittstelle prüfen.