Jeder Aufruf einer externen API schlägt früher oder später fehl: Das Netz bricht ab, das Gegensystem geht in Wartung, das Kontingent ist erschöpft oder die gesendeten Daten werden abgelehnt. Den größten Schaden in der Praxis richtet oft nicht die erste Störung an, sondern die Reaktion darauf: Ein dauerhafter Fehler wird endlos wiederholt, an ein ausgefallenes System gehen Hunderte Anfragen pro Sekunde, ein POST mit Timeout wird blind wiederholt und erzeugt eine doppelte Bestellung. Für Aufrufe an Systeme wie ERP, CRM, Zahlung und Microsoft 365 sollte eine Richtlinie für Retry, Backoff, Rate Limit, Timeout und Circuit Breaker von Anfang an schriftlich vorliegen.
Vorübergehende und dauerhafte Fehler unterscheiden
Erste Regel: Nur vorübergehende Fehler werden wiederholt. Ein vorübergehender Fehler ist einer, bei dem dieselbe Anfrage nach einiger Zeit unverändert gesendet Aussicht auf Erfolg hat: Verbindungs-Timeout, DNS-Auflösungsfehler, Überlastung des Gegensystems, Kontingentüberschreitung. Ein dauerhafter Fehler ist einer, dessen Ergebnis sich nicht ändert, solange sich die Anfrage nicht ändert: ungültiges Feld, unbefugter Zugriff, nicht gefundener Datensatz.
Einen dauerhaften Fehler zu wiederholen, verursacht zwei Schäden. Erstens bemerken Sie das eigentliche Problem (fehlendes Feld-Mapping, abgelaufenes Zertifikat) spät; das Log füllt sich mit Tausenden Wiederholungen desselben Fehlers, und die entscheidende Zeile geht unter. Zweitens wird bei einer Batch-Übertragung das Kontingent des Gegensystems verschwendet, wenn jeder von Tausenden Datensätzen mehrmals versucht wird, und auch fehlerfreie Anfragen sind betroffen. Ein einziger schlechter Datensatz blockiert den gesamten Fluss.
Zweite Regel: Die wiederholte Operation muss idempotent sein. RFC 9110 definiert die Methoden GET, PUT und DELETE als idempotent; POST nicht. Ein POST mit Timeout kann auf der Gegenseite verarbeitet worden sein. Nur weil der Client keine Antwort erhalten hat, heißt das nicht, dass nichts passiert ist. POST-Aufrufe, die Bestellungen oder Zahlungen anlegen, sollten nur dann automatisch wiederholt werden, wenn die Gegen-API einen Idempotency-Key (bei vielen Anbietern der Header Idempotency-Key) oder eine Duplikatprüfung über eine externe Referenznummer unterstützt.
Wiederholungstabelle nach HTTP-Statuscodes
| Status | Bedeutung | Wiederholen? |
|---|---|---|
| Verbindungsfehler, Timeout | Keine Antwort erhalten | Ja; bei POST nur mit Idempotency-Key |
| 400, 422 | Anfrage ungültig | Nein; Daten korrigieren |
| 401 | Authentifizierung fehlgeschlagen | Token erneuern und einmal; danach nein |
| 403, 404 | Keine Berechtigung / Ressource nicht vorhanden | Nein |
| 408 | Timeout des Servers beim Warten auf die Anfrage | Ja |
| 409 | Konflikt | Meist nein; Zustand lesen und entscheiden |
| 429 | Zu viele Anfragen | Ja; Retry-After beachten |
| 500 | Interner Serverfehler | In begrenzter Zahl |
| 502, 503, 504 | Gateway / Dienst nicht erreichbar | Ja, mit Backoff |
Diese Tabelle ist ein Standard, kein Vertrag. Manche APIs liefern bei Validierungsfehlern 500, manche melden Kontingentüberschreitung mit 403. Lesen Sie für jede integrierte API die Dokumentation, konfigurieren Sie die Tabelle für diese API und beziehen Sie auch den Fehlercode im Antwortkörper in die Klassifizierung ein. 500 wird nur begrenzt wiederholt, weil dieser Code sowohl eine vorübergehende Störung als auch einen Softwarefehler anzeigen kann, den eine bestimmte Anfrage jedes Mal auslöst. Erhält derselbe Datensatz jedes Mal 500, liegt das Problem nicht auf der Gegenseite, sondern bei diesem Datensatz.
Exponential Backoff, Jitter und Retry-After
Nach einem Fehler sofort und in festen Abständen erneut zu versuchen, belastet das problematische System erneut, ohne ihm Zeit zur Erholung zu geben. Exponential Backoff vervielfacht die Wartezeit bei jedem Versuch. Allein reicht das nicht: Wiederholen Hunderte gleichzeitig gescheiterte Clients in denselben Abständen, kehrt die Last in Wellen zurück. Jitter fügt der Wartezeit Zufall hinzu und löst diese Synchronisierung auf. Beim verbreiteten Ansatz „Full Jitter“ wird die Wartezeit zufällig zwischen null und der exponentiellen Obergrenze gewählt.
BASIS = 1.0 # Sekunden
OBERGRENZE = 30.0 # Obergrenze einer einzelnen Wartezeit
MAX_VERSUCHE = 5
for versuch in range(MAX_VERSUCHE + 1):
antwort = aufrufen(anfrage, timeout=verbleibendes_zeitbudget())
if antwort.erfolgreich:
return antwort
if not wiederholbar(antwort) or versuch == MAX_VERSUCHE:
raise DauerhafterFehler(antwort)
if antwort.retry_after is not None: # 429 / 503
warten = antwort.retry_after
else:
warten = random.uniform(0, min(OBERGRENZE, BASIS * 2 ** versuch))
if warten > verbleibendes_zeitbudget():
raise ZeitbudgetUeberschritten()
schlafen(warten)
Beispielrechnung: Mit einer Basis von 1 Sekunde betragen die Obergrenzen der Wartezeiten vor fünf Wiederholungen 1, 2, 4, 8 und 16 Sekunden; die Gesamtwartezeit liegt im schlimmsten Fall bei 31 Sekunden und mit den Timeouts der sechs Aufrufe einschließlich des ersten darüber. Die Obergrenze von 30 Sekunden greift bei dieser Einstellung nicht; wird die Zahl der Versuche erhöht, wird ab der sechsten Wiederholung jede Wartezeit auf 30 Sekunden begrenzt. Für einen Aufruf innerhalb einer Nutzeranfrage ist das viel zu lang. Für eine Hintergrundsynchronisierung ist es vertretbar. Legen Sie die Parameter je nach Kontext des Aufrufs getrennt fest; eine einzige globale Einstellung verdirbt beide Seiten.
Der Header Retry-After ist in RFC 9110 definiert und kann eine Zahl in Sekunden oder ein HTTP-Datum enthalten. Der Client muss beide Formate parsen und darf nicht kürzer warten als vom Server empfohlen. Kommt dieser Header, verwenden Sie statt Ihrer eigenen Backoff-Berechnung den Wert des Servers; das verhindert unnötige Ablehnungen in Kontingentfenstern. Ein Fehler, den wir in der Praxis häufig sehen: Ein Client, der nur das Zahlenformat parst, wartet beim Datumsformat null Sekunden und versucht es sofort erneut.
Rate Limit und Kontingentverwaltung
Der Statuscode 429 (Too Many Requests) ist in RFC 6585 definiert. Reagieren Sie nicht nur auf Kontingentfehler, sondern verwalten Sie das Kontingent vorab auf Client-Seite:
- Kontingent aus der Dokumentation entnehmen und im Client begrenzen. Halten Sie mit einem Rate Limiter wie Token Bucket die Zahl der Aufrufe pro Sekunde oder Minute unter dem Kontingent.
- Header zum Restkontingent lesen. Viele APIs melden verbleibende Anfragen und den Zeitpunkt des Fenster-Resets mit Headern wie
X-RateLimit-Remaining. Diese Header sind nicht standardisiert; Namen und Bedeutung variieren je nach API. - Alle Prozesse, die das Kontingent teilen, gemeinsam betrachten. Nachtübertragung, Webhook-Worker und Website, die denselben API-Schlüssel nutzen, verbrauchen dasselbe Kontingent. Die nächtliche Produktsynchronisierung erschöpft das Kontingent, und morgens erhalten Bestellungen 429. Geben Sie kritischen Flüssen (Bestellung) Vorrang und Batch-Flüssen (Produktsynchronisierung) niedrige Priorität.
- Batch-Endpunkte bevorzugen. Bietet die API einen Batch-Endpunkt, der mehrere Datensätze in einem Aufruf aktualisiert, nutzen Sie ihn statt eines Aufrufs pro Datensatz.
Auch Microsoft Graph liefert bei Drosselung (Throttling) 429 und Retry-After; bei Graph-API-Integrationen ist die Beachtung dieses Headers der grundlegende Weg, eine Verlängerung der Drosselung zu vermeiden. Ein Client, der den Header ignoriert und weiter drängt, wartet länger.
Timeout-Budget und Circuit Breaker
Ein HTTP-Client ohne definierten Timeout kann sehr lange auf einen nicht antwortenden Server warten; der Standard vieler Bibliotheken ist entweder sehr lang oder gar nicht vorhanden. Beim Code-Review ist das die erste Stelle zum Nachsehen. Legen Sie zwei getrennte Werte fest: einen kurzen Verbindungs-Timeout (TCP/TLS-Aufbau) und einen Lese-Timeout nach der normalen Antwortzeit der API.
Definieren Sie neben den einzelnen Timeouts ein Gesamtzeitbudget. Hat eine Web-Anfrage, auf die ein Nutzer wartet, z. B. ein Budget von 3 Sekunden und dauerte der erste Versuch 2,5 Sekunden, sollte kein zweiter Versuch erfolgen oder nur begrenzt auf die verbleibende Zeit. Dafür dient die Funktion verbleibendes_zeitbudget() im obigen Pseudocode.
Ist das Gegensystem vollständig ausgefallen und wartet jede Anfrage auf ihren Timeout, verbraucht das die Threads und den Verbindungspool Ihrer eigenen Anwendung. So breitet sich eine Störung aus. Der Circuit Breaker steuert diese Situation mit einem Mechanismus aus drei Zuständen:
| Zustand | Verhalten | Übergangsbedingung |
|---|---|---|
| Geschlossen (closed) | Aufrufe erfolgen normal, Fehler werden gezählt | Bei Überschreiten der Fehlerquote offen |
| Offen (open) | Ohne Aufruf wird sofort ein Fehler geliefert | Nach Ablauf der Wartezeit halb offen |
| Halb offen (half-open) | Eine begrenzte Zahl von Testaufrufen ist erlaubt | Bei Erfolg geschlossen, sonst offen |
Bieten Sie bei offenem Breaker ein sinnvolles Ersatzverhalten: etwa den letzten Preis aus dem Cache mit dem Hinweis „wird bestätigt“ anzeigen oder die Bestellung in die Queue stellen und im Status „in Bearbeitung“ belassen. Eine ausführliche Beschreibung des Musters finden Sie im Dokument Circuit Breaker pattern von Microsoft. Werden Retry und Circuit Breaker gemeinsam verwendet, muss die Retry-Schleife bei offenem Breaker die Versuche einstellen; sonst heben sich die beiden Mechanismen gegenseitig auf.
Dead-Letter für fehlgeschlagene Nachrichten
In Hintergrundintegrationen wird eine Nachricht, deren Versuche aufgebraucht sind, nicht stillschweigend gelöscht. Die Dead-Letter-Queue (DLQ) ist ein separater Bereich, in dem nicht verarbeitbare Nachrichten zusammen mit dem Fehlergrund warten. Broker wie RabbitMQ, Azure Service Bus und Amazon SQS bieten dieses Konzept eingebaut an; bei einfachen Queues auf Basis einer Datenbanktabelle erfüllt ein Feld status = 'dead' denselben Zweck. Eine gelöschte Nachricht kommt nicht zurück. Eine Nachricht im Dead-Letter wird korrigiert und erneut eingespielt.
Checkliste für die Dead-Letter-Verwaltung:
- Werden mit der Nachricht der letzte Fehlercode, die Fehlermeldung, die Zahl der Versuche und Zeitpunkt des ersten/letzten Versuchs gespeichert?
- Gehen dauerhafte Fehler (400, 422) ohne Wiederholung direkt ins Dead-Letter?
- Ist für die Zahl der Nachrichten im Dead-Letter ein Alarm definiert und ein Verantwortlicher benannt?
- Gibt es einen dokumentierten Weg, Nachrichten nach Behebung des Problems in die Haupt-Queue zurückzusenden (Replay)?
- Wurde geprüft, dass wieder eingespielte Nachrichten idempotent verarbeitet werden?
Größe und Alter der Dead-Letter-Queue sind zentrale Kennzahlen für die Gesundheit einer Integration; das Alarmdesign für diese Kennzahlen beschreibt der Leitfaden zu Integrationsmonitoring und Abgleich. Für die Entsprechung derselben Prinzipien auf der eingehenden Seite lesen Sie die Beiträge Webhook-Empfänger gestalten und, zur Frage welcher Fluss synchron und welcher über eine Queue laufen sollte, Integrationsmuster zwischen ERP und Web. Wenn Sie die Fehlerrichtlinie Ihrer bestehenden Integrationen überprüfen möchten, finden Sie Informationen auf unserer Seite ERP-, CRM- und API-Integrationen.
Häufig gestellte Fragen
Wie oft sollte wiederholt werden?
Eine universelle Zahl gibt es nicht; entscheidend ist das gesamte Zeitbudget. Bei Anfragen, auf die ein Nutzer wartet, genügen ein oder zwei kurze Versuche. Bei Hintergrundübertragungen sind mehr Versuche möglich, doch wenn die Versuche aufgebraucht sind, wird die Nachricht nicht gelöscht, sondern in den Dead-Letter-Bereich verschoben.
Ist es sicher, eine POST-Anfrage nach einem Timeout erneut zu senden?
Nur wenn die Gegen-API einen Idempotency-Key oder eine Duplikatprüfung über eine externe Referenznummer unterstützt. Andernfalls kann die erste Anfrage auf der Gegenseite bereits verarbeitet worden sein, und das erneute Senden erzeugt eine doppelte Bestellung oder Zahlung. Fragen Sie in diesem Fall zuerst ab, ob der Datensatz existiert.
Warum ist Jitter nötig, genügt Exponential Backoff nicht?
Wiederholen viele Clients, die gleichzeitig einen Fehler erhalten haben, in denselben exponentiellen Abständen, ballen sich die Anfragen wieder zu denselben Zeitpunkten und belasten das sich erholende System in Wellen. Jitter fügt der Wartezeit Zufall hinzu und verteilt diese Anfragen zeitlich.
Wie sollten Circuit Breaker und Retry zusammenarbeiten?
Retry toleriert den vorübergehenden Fehler einer einzelnen Anfrage; der Circuit Breaker stoppt Aufrufe vollständig, wenn das Gegensystem insgesamt ausgefallen ist. Die Retry-Schleife sollte vor jedem Versuch den Zustand des Breakers prüfen, bei offenem Breaker ohne Wartezeit einen Fehler liefern und zum Ersatzverhalten wechseln.