Wie man eine zuverlässige API-Fehlerbehandlung plant

Eine Bestellung im Webshop trifft ein, aber das Lagerverwaltungssystem reagiert nicht. Der Kunde erhält eine Bestätigung, die Bestellung erscheint jedoch nicht auf der Aufgabenliste des Lagers. Zwei Stunden später versucht ein Kollege, dies aus einer Tabelle zu rekonstruieren und erfasst die Daten manuell. Dies ist kein einfacher technischer Fehler: Es kann zu Bestandsabweichungen, verspäteten Lieferungen, fehlerhaften Rechnungen und Vertrauensverlust führen. Daher stellt sich nicht nur die Frage, wie man API-Fehlerbehandlung plant, sondern auch, wie der Geschäftsprozess bei einem Systemausfall steuerbar bleibt.

APIs verbinden typischerweise Systeme miteinander. Sie verknüpfen den Webshop mit ERP, Transportdienstleistern, Abrechnungssystemen, CRM oder Produktionsanwendungen. Solange alle Antworten schnell und erfolgreich sind, bleibt diese Verbindung unsichtbar. Im Fehlerfall zeigt sich jedoch, ob die Informationen tatsächlich übertragen wurden, wer für den nächsten Schritt verantwortlich ist und ob es eine Möglichkeit gibt, die Arbeit sicher fortzusetzen.

Die Fehlerbehandlung beginnt mit den geschäftlichen Konsequenzen

Der erste Fehler in vielen Organisationen ist, dass alle fehlgeschlagenen API-Aufrufe als gleichwertig betrachtet werden. Dabei gibt es wesentliche Unterschiede, ob ein Kurierdienst fünf Sekunden nicht erreichbar ist, wir uns mit einer falschen ID mit dem System eines Partners verbinden oder eine Bestellung ohne Postleitzahl vorliegt.

Die technische Nachricht allein hilft dem Betriebsteam selten. Ein „400 Bad Request“ sagt nicht, ob die Bestellung korrigierbar, erneut sendbar ist oder mit dem Kunden abgestimmt werden muss. Ein „500 Internal Server Error“ beantwortet nicht, ob die Bestellung verloren gegangen, zur Verarbeitung ausstehend ist oder im Zielsystem bereits erstellt wurde, nur die Antwort verloren ging.

Bevor wir Entwicklungsrichtlinien schreiben, ist es ratsam, den Prozess für jede wichtige Integration durchzugehen. Was löst die Datenübertragung aus? Welches System ist der Dateninhaber? Was passiert, wenn die Übertragung fehlschlägt? Wer sieht dies, mit welcher Frist, und wie kann die Korrektur überprüft werden? Eine Bestellung, Rechnung oder Fertigungsanweisung darf nicht zu einem „unsicheren Zustand“ werden, nur weil es zwischen zwei Systemen eine vorübergehende Kommunikationsstörung gab.

Wie plant man die API-Fehlerbehandlung pro Prozess?

Gute Planung beginnt nicht mit einer allgemeinen Fehlerliste, sondern mit der Identifizierung kritischer Geschäftsvorfälle. Die Übergabe einer Webshop-Bestellung erfordert einen anderen Schutz als die Synchronisation eines Produktbildes. Bei der Erstellung einer Rechnung oder einer Produktionsbestandsreservierung kann bereits eine einzige doppelte Anfrage finanzielle oder operative Probleme verursachen. Ein täglicher Bericht kann in der Regel einige Minuten Verzögerung tolerieren, solange die Datenintegrität erhalten bleibt.

Bei jedem Prozess sind drei Fragen nützlich:

1. Was sind die geschäftlichen Auswirkungen des Fehlers, wenn die Daten nicht rechtzeitig übermittelt werden?
2. Kann der Vorgang ohne schädliche Nebenwirkungen wiederholt werden?
3. Wann ist eine menschliche Entscheidung erforderlich und wann kann die Situation automatisch korrigiert werden?

Basierend auf den Antworten auf diese Fragen kann eine angemessene Fehlerbehandlung entwickelt werden. Nicht jeder Fehler erfordert sofortige Alarmierung. Wenn eine nicht kritische Datenaktualisierung mit drei Minuten Verzögerung eintrifft, erzeugt eine ständige telefonische Benachrichtigung eher Lärm. Wenn jedoch aufgrund einer fehlgeschlagenen Bestandsreservierung ein Produkt im Webshop verkauft wird, das nicht mehr auf Lager ist, ist eine sofortige und eindeutige Behandlung erforderlich.

Klare Fehlertypen definieren

Es ist sinnvoll, Fehler nicht nur nach HTTP-Codes, sondern nach Behandlungsart zu gruppieren. Zu den vorübergehenden Fehlern gehören beispielsweise Netzwerkunterbrechungen, überlastete Partnersysteme oder abgelaufene Zeitlimits. Bei diesen ist ein erneuter Versuch in der Regel gerechtfertigt. Dauerhafte Fehler, wie fehlerhafte Berechtigungen oder geänderte API-Verbindungen, lösen sich nicht durch Wiederholung. Hier ist technisches Eingreifen erforderlich.

Die dritte Gruppe sind Geschäfts- oder Regelverstöße. Dazu gehören eine fehlende Steuernummer, eine nicht vorhandene Artikelnummer, ein geschlossener Bestellstatus oder ein nicht erlaubter Rabatt. Diese müssen den verantwortlichen Mitarbeitern verständlich zurückgemeldet werden: Was muss korrigiert werden, wo, und was passiert nach der Korrektur.

Diese Unterscheidung schützt das Team davor, dieselbe fehlerhafte Bestellung hundertmal erneut zu senden, während eine andere, vorübergehend fehlgeschlagene Datenübertragung unbemerkt im Tagesgeschäft verloren geht.

Grenzen und Regeln für Wiederholungsversuche festlegen

Ein API-Anfrage zu wiederholen, scheint eine naheliegende Lösung zu sein, ist aber nicht immer sicher. Wenn ein System die Erstellung einer Rechnung erfolgreich abgeschlossen hat und die Verbindung vor der Antwort unterbrochen wurde, kann die erneut gesendete Anfrage eine zweite Rechnung erstellen. Dasselbe kann bei der Bestellaufnahme, Zahlungsanforderung oder Etikettenerstellung passieren.

Daher ist für kritische Vorgänge eine eindeutige Kennung erforderlich. Das empfangende System muss erkennen, dass es sich um dieselbe Geschäftsanforderung handelt und darf diese nicht erneut ausführen. Dies nennt man idempotentes Verhalten. Aus Führungsperspektive ist es einfach: Ein vorübergehender Fehler sollte keine doppelten finanziellen, lagertechnischen oder kundenkommunikativen Vorgänge verursachen.

Auch das Timing der Wiederholungsversuche muss geregelt werden. Einige Sekunden Wartezeit, gefolgt von schrittweise längeren Intervallen, sind oft angemessen. Ständige, sofortige Wiederholungen können das fehlerhafte System weiter belasten und das eigentliche Problem verdecken. Nach einer bestimmten Anzahl von Versuchen sollte der Fall auf eine überprüfbare Warteliste gesetzt werden, anstatt in den Logdateien zu verschwinden.

Der Kollege sollte nicht der Fehlerbeheber zwischen den Systemen sein

In vielen Unternehmen existiert die Fehlerbehebung bei Integrationen tatsächlich im Kopf eines erfahrenen Mitarbeiters. Er weiß, welche E-Mail gesucht werden muss, welches System neu gestartet werden muss und welche Daten manuell geändert werden müssen. Dies scheint eine schnelle Lösung zu sein, baut jedoch einen personengebundenen Prozess auf. Bei Urlaub, Krankheit oder Wachstum wird dies sofort zu einem Risiko.

Ein handhabbares System lässt den Benutzer nicht mit einer technischen Fehlermeldung allein. Die verantwortliche Rolle benötigt eine Aufgabenliste, in der das betroffene Geschäftsobjekt - zum Beispiel Bestellnummer, Partner oder Rechnung -, die Fehlerursache, die bisherigen Versuche und der nächste empfohlene Schritt sichtbar sind. Nach der Fehlerbehebung muss der Prozess regelkonform fortgesetzt werden können, möglichst ohne manuelle Datenkopie.

Das bedeutet nicht, dass jede Ausnahme automatisiert werden muss. Die Lieferbedingungen einer Bestellung eines wichtigen Kunden oder ein ungewöhnlicher Produktionsauftrag können eine echte menschliche Abwägung erfordern. Das Ziel ist, dass der Kollege Entscheidungen trifft, anstatt zwischen Systemen Daten zu jagen und dieselbe Information mehrfach einzugeben.

Protokollierung und Überwachbarkeit: Beweise statt Annahmen

Wenn ein Manager fragt, „ist diese Bestellung durchgegangen?“, muss das System eine klare Antwort geben. Dazu benötigt jede wichtige API-Operation eine nachverfolgbare Kennung, einen Zeitstempel, ein Anforderungsergebnis, einen Verarbeitungsstatus und - wo angebracht - den detaillierten Grund des Fehlers. Persönliche, Zahlungs- oder andere sensible Daten dürfen natürlich nicht unkontrolliert protokolliert werden.

Das Protokoll allein ist jedoch kein Betriebsmodell. Man muss die Rate fehlgeschlagener Aufrufe, die Länge der Verarbeitungsschlangen, die Verschlechterung der Antwortzeiten und wiederkehrende Geschäftsdataprobleme überwachen. Wenn dieselbe Partnerartikelnummer wöchentlich einen Fehler verursacht, handelt es sich nicht um einen einmaligen Vorfall, sondern um ein Datenmanagement- oder Prozessproblem.

Es ist auch sinnvoll zu messen, wie viel Zeit zwischen Fehlerentstehung und -behebung vergeht, wie viele Geschäftsvorfälle auf Verarbeitung warten und wie oft menschliches Eingreifen erforderlich ist. Diese Kennzahlen beschreiben nicht nur die IT-Leistung. Sie zeigen, wie vorhersehbar die Auftragsabwicklung, der Lagerbetrieb oder die Finanzverwaltung ist.

Auch auf Fehler in Partnerbeziehungen muss man vorbereitet sein

Nicht jede API ist mit einem eigenen System verbunden. Spediteure, Zahlungsdienstleister, Lieferantenplattformen und Kundensysteme können ebenfalls Teil des Prozesses sein. In solchen Fällen hängen Verfügbarkeit, Antwortzeit, Versionswechsel und Datenqualität teilweise von externen Akteuren ab.

Eine gute Architektur baut daher nicht auf unbegrenztem Vertrauen auf. Sie definiert Zeitlimits, beschränkt wiederholte Anfragen an fehlerhafte Partner und trennt, wo der Geschäftsprozess es erlaubt, das unmittelbare Kundenerlebnis von der Hintergrundverarbeitung. Eine Bestellung kann beispielsweise intern erfasst werden, auch wenn das Versandetikett erst später erstellt wird. Dies sollte jedoch nur geschehen, wenn klar ist, wer und wann die spätere Erfüllung überprüft.

Auch das Änderungsmanagement gehört dazu. Eine Änderung der Felder oder Regeln einer externen API wird früher oder später eintreten. Mit versionierten Verbindungen, Testumgebungen und kontrollierter Einführung bleibt die Änderung eine planbare Aufgabe und wird nicht zu einem Betriebsstörfall am Montagmorgen.

Gute API-Fehlerbehandlung verspricht letztlich nicht, dass es nie zu Fehlern kommt. Sie stellt sicher, dass im Fehlerfall der Zustand des Geschäftsprozesses bekannt bleibt, der nächste Schritt klar ist und die Organisation nicht auf die Routine einer einzigen Person oder manuelle Tabellen angewiesen ist. Von hier aus lohnt es sich, weiterzudenken: Bei welcher aktuellen Systemverbindung könnten Sie heute nicht nachweisen, was nach einer fehlgeschlagenen Datenübertragung passiert ist?