Wie man eine zuverlässige API-Fehlerbehandlung plant

Eine Bestellung im Webshop trifft ein, aber das Lagerverwaltungssystem reagiert gerade 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, fehlerhafter Rechnungsstellung und Vertrauensverlust führen. Daher stellt sich nicht nur die Frage, wie man API-Fehlerbehandlung plant, sondern auch, wie der Geschäftsprozess bei einem Systemfehler steuerbar bleibt.

APIs stellen typischerweise eine Verbindung zwischen Systemen dar. Sie verbinden einen Webshop mit einem ERP, einem Transportunternehmen, einer Rechnungsstellung, einem CRM oder einer Produktionsanwendung. Solange alle Antworten schnell und erfolgreich sind, bleibt diese Verbindung unsichtbar. Bei einem Fehler stellt sich jedoch heraus, 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.

Fehlerbehandlung beginnt bei den geschäftlichen Konsequenzen

Der erste Fehler in vielen Organisationen ist, dass alle fehlgeschlagenen API-Aufrufe als gleichwertig behandelt werden. Dabei gibt es wesentliche Unterschiede zwischen der vorübergehenden Nichterreichbarkeit eines Kurierdienstes, einer fehlerhaften Identifikation bei der Verbindung mit einem Partnersystem oder einer fehlenden Postleitzahl in einer Bestellung.

Die technische Nachricht allein hilft dem operativen Team selten weiter. Ein „400 Bad Request“ sagt nicht, ob die Bestellung korrigierbar, erneut sendbar ist oder ob der Kunde kontaktiert werden muss. Ein „500 Internal Server Error“ beantwortet nicht, ob die Bestellung verloren gegangen ist, auf Verarbeitung wartet oder im Zielsystem bereits erstellt wurde, nur die Antwort verloren ging.

Bevor Entwicklungsrichtlinien geschrieben werden, sollte der Prozess für jede wichtige Integration durchgegangen werden. 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 Produktionsanweisung darf nicht zu einem „unsicheren Zustand“ werden, nur weil es zwischen zwei Systemen zu einer vorübergehenden Kommunikationsstörung gekommen ist.

Wie plant man die API-Fehlerbehandlung pro Prozess?

Eine gute Planung beginnt nicht mit einer allgemeinen Fehlerliste, sondern damit, dass kritische Geschäftsvorfälle identifiziert werden. Die Übergabe einer Bestellung im Webshop erfordert einen anderen Schutz als die Synchronisierung eines Produktbildes. Bei der Erstellung einer Rechnung oder einer Produktionsbestandsreservierung kann eine einzige doppelte Anfrage finanzielle oder operative Probleme verursachen. Eine tägliche Berichtsaktualisierung kann in der Regel einige Minuten Verzögerung tolerieren, solange die Datenintegrität erhalten bleibt.

Bei jedem Prozess sind drei Fragen hilfreich:

1. Welche geschäftlichen Auswirkungen hat der Fehler, wenn die Daten nicht rechtzeitig übertragen 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 diesen Antworten 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 ein fehlgeschlagener Bestandsreservierung dazu führt, dass ein Produkt verkauft wird, das nicht mehr auf Lager ist, ist eine sofortige und klare Behandlung erforderlich.

Es sollten klare Fehlertypen vorhanden sein

Es ist sinnvoll, Fehler nicht nur nach HTTP-Codes, sondern nach Behandlungsart zu gruppieren. Zu den vorübergehenden Fehlern gehören beispielsweise Netzwerkunterbrechungen, ein überlastetes Partnersystem oder ein abgelaufenes Zeitlimit. Bei diesen ist ein erneuter Versuch in der Regel gerechtfertigt. Dauerhafte Fehler, wie fehlerhafte Berechtigungen oder geänderte API-Verbindungen, werden durch Wiederholung nicht gelöst. Hier ist technisches Eingreifen erforderlich.

Die dritte Gruppe sind Geschäfts- oder Regelverstöße. Dazu gehören fehlende Steuernummern, nicht vorhandene Artikelnummern, geschlossene Bestellstatus oder nicht zulässige Rabatte. 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 täglichen Geschäft verloren geht.

Wiederholungsversuche sollten Grenzen und Regeln haben

Ein API-Anfrage-Wiederholungsversuch scheint eine naheliegende Lösung zu sein, ist aber nicht immer sicher. Wenn ein System die Rechnungserstellung erfolgreich durchgeführt hat, die Verbindung jedoch vor der Antwort unterbrochen wurde, kann die erneut gesendete Anfrage eine zweite Rechnung erstellen. Dasselbe kann bei der Bestellungsaufnahme, Zahlungsanforderung oder Etikettenerstellung passieren.

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

Auch das Timing der Wiederholungsversuche muss geregelt werden. Einige Sekunden, gefolgt von allmählich längeren Wartezeiten, sind in vielen Fällen angemessen. Ständige, sofortige Wiederholungen können jedoch 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 und nicht in den Protokolldateien verschwinden.

Der Kollege sollte nicht der Fehlerbeheber zwischen den Systemen sein

In vielen Unternehmen existiert die Fehlerbehandlung der Integration eigentlich im Kopf eines erfahrenen Mitarbeiters. Er weiß, welche E-Mail zu suchen ist, in welchem System der Vorgang neu gestartet werden muss und welche Daten manuell geändert werden müssen. Dies mag eine schnelle Lösung sein, baut jedoch einen personenabhängigen 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. Für die verantwortliche Rolle ist eine Aufgabenliste erforderlich, in der das betroffene Geschäftsobjekt - z.B. Bestellnummer, Partner oder Rechnung -, die Fehlerursache, die bisherigen Versuche und der nächste empfohlene Schritt sichtbar sind. Nach der Fehlerbehebung sollte der Prozess ordnungsgemäß 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 Produktionsposten können eine echte menschliche Abwägung erfordern. Das Ziel ist, dass der Kollege eine Entscheidung trifft und nicht zwischen Systemen nach Daten jagt und dieselben Informationen an mehreren Stellen eingibt.

Protokollierung und Beobachtbarkeit: Beweise sind erforderlich, keine Annahmen

Wenn ein Manager fragt: „Ist diese Bestellung durchgegangen?“, muss das System eine eindeutige Antwort geben. Dazu ist bei jeder wichtigen API-Operation eine nachverfolgbare Kennung, ein Zeitstempel, ein Anfrageergebnis, ein Verarbeitungsstatus und - wo erforderlich - der detaillierte Fehlergrund erforderlich. Persönliche, Zahlungs- oder andere sensible Daten dürfen natürlich nicht unkontrolliert protokolliert werden.

Das Protokoll allein ist jedoch kein Betriebsmodell. Es muss auf das Verhältnis fehlgeschlagener Aufrufe, die Länge der Verarbeitungsschlangen, die Verschlechterung der Antwortzeiten und wiederkehrende Geschäftsdataprobleme geachtet werden. Wenn dieselbe Partnerartikelnummer wöchentlich einen Fehler verursacht, handelt es sich nicht um einen einmaligen Vorfall, sondern um ein Datenverwaltungs- 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 Indikatoren beschreiben nicht nur die IT-Leistung. Sie zeigen, wie vorhersehbar die Auftragsabwicklung, der Lagerbetrieb oder die Finanzverwaltung ist.

Auch auf Fehler in den 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 die Verfügbarkeit, die Antwortzeit, der Versionswechsel und die Datenqualität teilweise von externen Akteuren ab.

Eine gute Architektur baut daher nicht auf unbegrenztem Vertrauen. Sie definiert Zeitlimits, beschränkt wiederholte Anfragen an fehlerhafte Partner und trennt, wo der Geschäftsprozess dies zulässt, das sofortige Kundenerlebnis von der Hintergrundverarbeitung. Eine Bestellung kann beispielsweise intern erfasst werden, auch wenn das Versandetikett erst später erstellt wird. Dies sollte jedoch nur dann 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 zum Betriebsstörung am Montagmorgen.

Eine gute API-Fehlerbehandlung verspricht letztlich nicht, dass nie ein Fehler auftritt. Sie stellt sicher, dass im Fehlerfall der Status des Geschäftsprozesses bekannt bleibt, der nächste Schritt klar ist und die Organisation sich nicht auf die Routine eines Einzelnen oder manuelle Tabellen stützt. Von hier aus lohnt es sich, weiterzudenken: Bei welcher Ihrer aktuellen Systemverbindungen könnten Sie heute nicht nachweisen, was nach einer fehlgeschlagenen Datenübertragung passiert ist?