Sichere Integration von Drittanbieter‑APIs: Wiederholungen, Timeouts, Circuit Breaker

Warum Drittanbieter‑APIs Ihre Kern‑Workflows blockieren können

Eine Drittanbieter‑API kann auf Arten ausfallen, die nicht wie ein klarer „Ausfall“ aussehen. Das häufigste Problem ist Langsamkeit: Anfragen hängen, Antworten kommen spät und Ihre App wartet weiter. Wenn diese Aufrufe auf dem kritischen Pfad liegen, häuft sich ein kleines Problem außerhalb Ihrer Kontrolle im Inneren Ihres Systems.

So wird ein lokaler Performance‑Einbruch zu einem kompletten Ausfall. Threads oder Worker bleiben wartend hängen, Warteschlangen wachsen, Datenbanktransaktionen dauern länger, und neue Anfragen beginnen zu timeouten. Bald fühlen sich selbst Seiten, die die externe API nicht nutzen, kaputt an, weil das System durch wartende Arbeit überlastet ist.

Die Auswirkungen sind konkret. Ein unzuverlässiger Identitätsanbieter blockiert Registrierungen und Logins. Ein Timeout beim Zahlungsanbieter friert den Checkout ein und lässt Nutzer unsicher, ob abgebucht wurde. Verzögerte Nachrichten stoppen Passwort‑Resets und Bestellbestätigungen, was eine zweite Welle von Wiederholungen und Support‑Tickets auslöst.

Das Ziel ist einfach: externe Fehler isolieren, damit die Kern‑Workflows weiterlaufen. Das kann bedeuten, dass ein Nutzer eine Bestellung aufgeben kann, während Sie die Zahlung später bestätigen, oder dass die Anmeldung gelingt, auch wenn die Willkommensmail fehlschlägt.

Ein praktischer Erfolgsmesser: Wenn ein Provider langsam oder ausgefallen ist, sollte Ihre App trotzdem schnell und klar antworten und der Explosionsradius klein bleiben. Beispielsweise sollten die meisten Kernanfragen weiterhin innerhalb Ihres normalen Latenzbudgets fertig werden, Fehler sich auf Features beschränken, die wirklich von dieser API abhängen, Nutzer einen klaren Status sehen (queued, pending, try again later) und die Wiederherstellung automatisch erfolgen, wenn der Provider zurückkommt.

Die Ausfallarten, auf die Sie sich vorbereiten sollten

Die meisten Ausfälle sind vorhersehbar, auch wenn ihr Zeitpunkt es nicht ist. Benennen Sie sie im Voraus, dann können Sie entscheiden, was wiederholt werden soll, was gestoppt wird und was dem Nutzer angezeigt wird.

Die häufigen Kategorien:

• Latenz‑Spikes (Anfragen, die plötzlich 10× länger dauern)
• Transiente Server‑ oder Netzwerkfehler (Timeouts, 502/503, Verbindungsabbrüche)
• Ratenbegrenzungen und Quotenerschöpfung (429s, Tageslimits)
• Auth‑ und Berechtigungsprobleme (abgelaufene Keys, widerrufener Zugang)
• Schlechte oder überraschende Daten (fehlende Felder, falsche Formate, partielle Antworten)

Nicht alle Fehler bedeuten dasselbe. Transiente Probleme sind oft einen Retry wert, weil der nächste Aufruf erfolgreich sein kann (Netzwerkstörungen, Timeouts, 502/503 und manche 429s nach Wartezeit). Permanente Probleme lösen sich in der Regel nicht von selbst (ungültige Anmeldeinformationen, falsche Endpunkte, fehlerhafte Anfragen, Berechtigungsverweigerungen).

Alle Fehler gleich zu behandeln verwandelt einen kleinen Vorfall in Downtime. Permanente Fehler immer wieder zu wiederholen verschwendet Zeit, trifft Ratenlimits schneller und baut einen Rückstau auf, der alles andere verlangsamt. Niemals transiente Fehler zu wiederholen zwingt Nutzer, Aktionen zu wiederholen, und verwirft Arbeit, die kurz darauf hätte abgeschlossen werden können.

Geben Sie Workflows besondere Aufmerksamkeit, bei denen eine Pause sich wie ein Abbruch anfühlt: Checkout, Login, Passwort‑Reset und Benachrichtigungen (E‑Mail/SMS/Push). Ein Zwei‑Sekunden‑Spike in einer Marketing‑API ist ärgerlich. Ein Zwei‑Sekunden‑Spike bei der Zahlungsautorisierung blockiert Umsatz.

Ein hilfreicher Test lautet: „Muss dieser Aufruf jetzt unbedingt die Hauptaufgabe des Nutzers abschließen?“ Wenn ja, brauchen Sie enge Timeouts, sorgfältige Wiederholungen und einen klaren Fehlerpfad. Wenn nein, verschieben Sie ihn in eine Warteschlange und halten die App reaktionsfähig.

Timeouts: Legen Sie ein Limit fest und halten Sie sich daran

Ein Timeout ist die maximale Zeit, die Sie warten, bevor Sie abbrechen und weiterziehen. Ohne klares Limit kann ein langsamer Provider wartende Anfragen anhäufen und wichtige Arbeit blockieren.

Es hilft, zwei Arten des Wartens zu trennen:

• Connect‑Timeout: wie lange Sie versuchen, eine Verbindung herzustellen.
• Read‑Timeout: wie lange Sie nach dem Verbindungsaufbau auf eine Antwort warten.

Zahlen zu wählen ist keine Frage der Perfektion. Es geht darum, menschliche Geduld und Ihren Workflow abzugleichen.

• Wenn ein Nutzer auf ein Lade‑Icon starrt, brauchen Sie meist eine schnelle Antwort und einen klaren nächsten Schritt.
• Wenn es ein Hintergrundjob ist (z. B. nächtliches Abgleichen von Rechnungen), können Sie mehr Zeit zulassen, aber es braucht trotzdem eine Obergrenze, damit er nicht ewig hängt.

Eine praktische Methode ist, rückwärts vom Erlebnis zu rechnen:

• Wie lange kann ein Nutzer warten, bevor Sie eine klare Meldung zeigen müssen?
• Wenn dieser Aufruf jetzt fehlschlägt, können Sie später erneut versuchen oder eine Fallback‑Option nutzen?
• Wie viele dieser Aufrufe laufen zur Spitzenzeit?

Der Trade‑off ist real. Zu lange Timeouts binden Threads, Worker und Datenbankverbindungen. Zu kurze Timeouts erzeugen falsche Fehler und lösen unnötige Wiederholungen aus.

Wiederholungen (Retries), die Ausfälle nicht verschlimmern

Retries helfen, wenn ein Fehler wahrscheinlich vorübergehend ist: ein kurzer Netzwerkfehler, DNS‑Hickup oder ein einmaliger 500/502/503. In diesen Fällen kann ein zweiter Versuch gelingen und die Nutzer merken nichts.

Das Risiko ist ein Retry‑Sturm. Wenn viele Clients gleichzeitig fehlschlagen und alle gleichzeitig wiederholen, können sie den Provider (und Ihre eigenen Worker) überlasten. Backoff und Jitter verhindern das.

Ein Retry‑Budget hält Sie ehrlich. Halten Sie die Versuche niedrig und begrenzen Sie die Gesamtzeit, damit Kern‑Workflows nicht wartend blockiert werden.

Ein sicheres Standard‑Retry‑Rezept

• Wiederholen Sie nur wenige Male (oft 1–3 Versuche insgesamt, je nach Ablauf).
• Verwenden Sie exponentielles Backoff (z. B. 200 ms, 500 ms, 1 s) plus zufälligen Jitter.
• Begrenzen Sie die insgesamt für Wiederholungen aufgewendete Zeit (bei Nutzer‑Flows oft nur wenige Sekunden).
• Verwenden Sie pro Versuch ein Timeout statt eines langen Timeouts für alle Versuche zusammen.

Wiederholen Sie vorhersehbare Client‑Fehler wie 400/422 Validierungsfehler, 401/403 Auth‑Probleme oder 404 nicht. Diese schlagen sehr wahrscheinlich wieder fehl und erzeugen nur zusätzliche Last.

Noch eine Schutzmaßnahme: Wiederholen Sie Schreib‑Operationen (POST/PUT) nur, wenn Sie Idempotenz implementiert haben, sonst riskieren Sie Doppellasten oder doppelte Datensätze.

Idempotenz: Machen Sie Wiederholungen in echten Workflows sicher

Idempotenz bedeutet, dass Sie dieselbe Anfrage zweimal ausführen können und am Ende dasselbe Ergebnis erhalten. Das ist wichtig, weil Retries normal sind: Netzwerke fallen aus, Server starten neu und Clients timeouten. Ohne Idempotenz erzeugt ein „hilfreicher“ Retry Duplikate und reale Geldprobleme.

Stellen Sie sich den Checkout vor: die Zahlungs‑API ist langsam, Ihre App time‑outet und Sie wiederholen. Wenn der erste Aufruf tatsächlich erfolgreich war, könnte der Retry eine zweite Abbuchung erzeugen. Dasselbe Risiko besteht bei Aktionen wie Bestellung anlegen, Abonnement starten, E‑Mail/SMS senden, Rückzahlung veranlassen oder ein Support‑Ticket anlegen.

Die Lösung ist, jeder „mach etwas“‑Anfrage einen Idempotenz‑Schlüssel (oder Request‑ID) beizufügen. Er sollte eindeutig pro Nutzeraktion sein, nicht pro Versuch. Der Provider (oder Ihr eigener Service) nutzt diesen Schlüssel, um Duplikate zu erkennen und dasselbe Ergebnis zurückzugeben, statt die Aktion erneut auszuführen.

Behandeln Sie den Idempotenz‑Schlüssel wie Teil des Datenmodells, nicht wie einen Header, den man hoffentlich nicht vergisst.

Ein Muster, das in Produktion hält

Erzeugen Sie einen Schlüssel, wenn der Nutzer die Aktion startet (z. B. beim Klick auf „Bezahlen“), und speichern Sie ihn mit Ihrem lokalen Datensatz.

Bei jedem Versuch:

• Senden Sie denselben Schlüssel.
• Speichern Sie das finale Ergebnis (Erfolgsantwort, Fehlercode, Charge‑ID).
• Wenn Sie bereits ein aufgezeichnetes Ergebnis haben, geben Sie dieses zurück, anstatt die Aktion zu wiederholen.

Wenn Sie der „Provider“ für interne Aufrufe sind, erzwingen Sie dasselbe Verhalten serverseitig.

Circuit Breaker: Rufen Sie die API nicht mehr an, wenn sie fehlschlägt

Ein Circuit Breaker ist ein Schutzschalter. Wenn ein externer Dienst zu oft fehlschlägt, hören Sie für eine kurze Zeit auf, ihn aufzurufen, statt weitere wahrscheinlich zeitintensive Anfragen zu stapeln.

Circuit Breaker haben typischerweise drei Zustände:

• Closed: Anfragen fließen normal.
• Open: Aufrufe sind für ein Cooldown‑Fenster blockiert.
• Half‑open: Nach dem Cooldown prüfen wenige Testaufrufe, ob der Dienst wiederhergestellt ist.

Wenn der Breaker offen ist, sollte Ihre App etwas Vorhersehbares tun. Wenn eine Adressvalidierungs‑API bei der Registrierung ausfällt, akzeptieren Sie die Adresse und markieren sie zur späteren Überprüfung. Ist eine Zahlungs‑Risikoüberprüfung down, legen Sie die Bestellung zur manuellen Prüfung in die Queue oder deaktivieren die Option vorübergehend und erklären warum.

Wählen Sie Schwellenwerte, die zum Nutzer‑Impact passen:

• aufeinanderfolgende Fehler (z. B. 5 Fehler in Folge)
• hohe Fehlerquote über ein kurzes Fenster
• viele langsame Antworten (Timeouts)
• spezifische Statuscodes (wiederholte 503s)

Halten Sie Cooldowns kurz (Sekunden bis eine Minute) und begrenzen Sie Half‑Open‑Probes. Das Ziel ist, zuerst Kern‑Workflows zu schützen und dann schnell zu erholen.

Fallbacks und Warteschlangen: Die App benutzbar halten

Wenn eine externe API langsam oder ausgefallen ist, ist Ihr Ziel, den Nutzer weiterkommen zu lassen. Das heißt, Sie brauchen einen Plan B, der ehrlich erklärt, was passiert ist.

Fallbacks: Ein „gut genug“ Erlebnis wählen

Ein Fallback ist, was Ihre App tut, wenn die API nicht rechtzeitig antwortet. Optionen sind: gecachte Daten verwenden, in einen degradierten Modus wechseln (nicht‑essentielle Widgets ausblenden, optionale Aktionen deaktivieren), den Nutzer nach Eingaben fragen statt die API zu rufen (manuelle Adresseneingabe) oder eine klare Meldung mit dem nächsten Schritt zeigen.

Seien Sie ehrlich: Sagen Sie nicht, etwas sei abgeschlossen, wenn es das nicht ist.

Warteschlangen: Später erledigen, wenn „jetzt“ nicht nötig ist

Wenn die Arbeit nicht in der Nutzeranfrage abgeschlossen sein muss, schieben Sie sie in eine Warteschlange und antworten Sie schnell. Übliche Kandidaten: E‑Mails senden, zu einem CRM synchronisieren, Reports erzeugen und Analyse‑Events posten.

Schnell fehlschlagen für Kern‑Aktionen. Wenn eine API nicht erforderlich ist, um den Checkout (oder die Kontoerstellung) abzuschließen, blockieren Sie die Anfrage nicht. Akzeptieren Sie die Bestellung, legen Sie den externen Aufruf in die Queue und gleichen Sie später ab. Wenn die API erforderlich ist (z. B. Zahlungsautorisierung), schlagen Sie schnell mit einer klaren Meldung fehl und lassen den Nutzer nicht ewig warten.

Was der Nutzer sieht, sollte zu dem passen, was hinter den Kulissen passiert: ein klarer Status (completed, pending, failed), ein Versprechen, das Sie halten können (Quittung jetzt, Bestätigung später), eine Möglichkeit zum Retry und ein sichtbarer Eintrag in der UI (Aktivitätsprotokoll, Pending‑Badge).

Ratenbegrenzungen und Last: Vermeiden Sie selbstverschuldete Fehler

Ratenbegrenzungen sind die Art eines Providers zu sagen: „Ihr könnt uns anrufen, aber nicht zu oft.“ Sie erreichen sie schneller, als Sie denken: Traffic‑Spikes, gleichzeitig startende Hintergrundjobs oder ein Bug, der bei Fehlern in einer Schleife landet.

Fangen Sie damit an, zu kontrollieren, wie viele Anfragen Sie erzeugen. Batches bilden, Antworten 30–60 Sekunden cachen, wenn es sicher ist, und clientseitig drosseln, damit Ihre App nicht schneller ausbricht, als der Provider erlaubt.

Bei einem 429 Too Many Requests behandeln Sie das als Signal langsamer zu werden.

• Respektieren Sie Retry‑After, wenn er bereitgestellt wird.
• Fügen Sie Jitter hinzu, damit nicht viele Worker gleichzeitig retryen.
• Begrenzen Sie Retries für 429s, um endlose Schleifen zu vermeiden.
• Backoff stärker bei wiederholten 429s.
• Messen Sie es als Metrik, damit Sie Muster bemerken, bevor Nutzer es tun.

Begrenzen Sie außerdem Parallelität. Ein einzelner Workflow (z. B. Kontaktsynchronisation) sollte nicht alle Worker‑Slots verbrauchen und kritische Flows wie Login oder Checkout aushungern. Separate Pools oder feature‑basierte Caps helfen.

Schritt‑für‑Schritt: Ein sicheres Standard‑Integrations‑Rezept

Jeder Drittanbieter‑Aufruf braucht einen Plan für Fehler. Perfektion ist nicht nötig. Sie brauchen vorhersehbares Verhalten, wenn der Provider einen schlechten Tag hat.

1) Klassifizieren Sie den Aufruf (must‑have vs can‑wait)

Entscheiden Sie, was passiert, wenn der Aufruf jetzt fehlschlägt. Eine Steuerberechnung beim Checkout ist eventuell must‑have. Das Synchronisieren eines Marketing‑Kontakts kann meist warten. Diese Entscheidung bestimmt den Rest.

2) Setzen Sie Timeouts und ein Retry‑Budget

Wählen Sie Timeouts pro Aufruftyp und halten Sie sie konsistent. Legen Sie dann ein Retry‑Budget fest, damit Sie eine langsam arbeitende API nicht weiter bearbeiten.

• Must‑have, Nutzer wartet: kurzes Timeout, 0–1 Retry.
• Can‑wait, Hintergrundjob: längeres Timeout, einige Retries mit Backoff.
• Niemals ewig retryen: begrenzen Sie die Gesamtzeit pro Task.

3) Machen Sie Retries sicher mit Idempotenz und Tracking

Wenn eine Anfrage etwas erstellen oder Geld abbuchen kann, fügen Sie Idempotency‑Keys hinzu und speichern Sie einen Request‑Datensatz. Wenn eine Zahlungsanfrage time‑outet, darf ein Retry nicht doppelt abbuchen. Tracking hilft dem Support bei der Antwort auf „Ist es durchgegangen?“

4) Fügen Sie einen Circuit Breaker und Fallback‑Verhalten hinzu

Wenn Fehler steigen, hören Sie kurz auf, den Provider aufzurufen. Für must‑have Calls zeigen Sie einen klaren „Erneut versuchen“‑Pfad. Für can‑wait Calls legen Sie die Arbeit in die Queue und verarbeiten sie später.

5) Überwachen Sie das Wesentliche

Messen Sie Latenz, Fehlerquote und Breaker‑Open/Close‑Ereignisse. Alerten Sie bei anhaltenden Änderungen, nicht bei einzelnen Ausreißern.

Häufige Fehler, die einen kleinen Vorfall in Downtime verwandeln

Die meisten API‑Ausfälle starten nicht groß. Sie werden groß, weil Ihre App auf die schlechtestmögliche Weise reagiert: sie wartet zu lange, retryt zu aggressiv und bindet genau die Worker, die sonst alles am Laufen halten.

Diese Muster verursachen Kaskaden:

• Jeden Fehler retryen, auch 4xx‑Probleme wie ungültige Anfragen, abgelaufene Auths oder fehlende Berechtigungen.
• Sehr lange Timeouts setzen „um sicherzugehen“, die still Threads, DB‑Verbindungen oder Job‑Runner verbrauchen, bis keine Kapazität mehr da ist.
• Create‑Aufrufe ohne Idempotenz wiederholen, was zu Doppelabbuchungen, doppelten Sendungen oder wiederholten Datensätzen führt.
• Falsch konfigurierte Circuit Breaker, die nie wieder schließen oder ständig auf‑ und zu‑gehen.
• Teilweise Ausfälle als Totalausfall behandeln, statt nur das betroffene Feature zu degradieren.

Kleine Fixes verhindern große Ausfälle: Retryen Sie nur Fehler, die wahrscheinlich temporär sind (Timeouts, manche 429s, manche 5xx) und begrenzen Sie Versuche mit Backoff und Jitter; halten Sie Timeouts kurz und bewusst; fordern Sie Idempotenz für jede Operation, die erstellt oder belastet; und entwerfen Sie für partielle Ausfälle.

Schnell‑Checkliste vor dem Produktivstart

Bevor Sie eine Integration in Produktion bringen, machen Sie einen schnellen Pass mit einer Fail‑First‑Mentalität. Wenn Sie eine Frage nicht mit „ja“ beantworten können, behandeln Sie sie als Release‑Blocker für Kern‑Workflows wie Signup, Checkout oder das Versenden von Nachrichten.

• Zeitlimits sind explizit (Connect‑Timeout und Read/Response‑Timeout).
• Retries sind limitiert (kleines Retry‑Budget, Backoff, Jitter und eine Gesamtzeitbegrenzung).
• Retries sind für reale Aktionen sicher (Idempotency‑Keys oder klare Dedupe‑Checks).
• Es gibt einen Breaker und einen Plan B (Fallback, degradierter Modus oder Queue).
• Sie können Probleme früh sehen (Latenz, Fehlerquote und Abhängigkeits‑Gesundheit pro Provider und Endpoint).

Wenn ein Zahlungsanbieter zu time‑outen beginnt, ist das richtige Verhalten: „Der Checkout lädt weiter, der Nutzer bekommt eine klare Meldung und Sie hängen nicht ewig“, nicht „alles hängt, bis es time‑outet."

Beispiel: Checkout schützen, wenn ein Provider unzuverlässig ist

Stellen Sie sich einen Checkout vor, der drei Dienste anruft: eine Zahlungs‑API zur Abbuchung, eine Steuer‑API zur Berechnung der Steuer und eine E‑Mail‑API zum Versand der Quittung.

Der Zahlungsaufruf ist der einzige, der synchron sein muss. Probleme bei Steuer oder E‑Mail dürfen den Kauf nicht blockieren.

Wenn die Steuer‑API langsam ist

Angenommen, die Steuer‑API braucht manchmal 8–15 Sekunden. Wartet der Checkout, brechen Nutzer ab und Ihre Worker hängen.

Ein sicherer Ablauf:

• Setzen Sie ein hartes Timeout (z. B. 800 ms bis 2 s) und schlagen Sie schnell fehl.
• Retryen Sie höchstens einmal, nur wenn es sicher ist, mit Jitter.
• Verwenden Sie bei Timeout einen gecachten Satz oder zuletzt bekannte Tabelle für die Region des Käufers.
• Wenn Sie gesetzlich keine gecachten Sätze verwenden dürfen, markieren Sie die Bestellung als „pending tax“ und legen Sie eine Neuberechnung in die Queue.

Ergebnis: weniger abgebrochene Warenkörbe und weniger festhängende Bestellungen, wenn der Steuer‑Provider langsam ist.

Wenn die E‑Mail‑API ausfällt

Die Quittungs‑E‑Mail ist wichtig, darf aber nie die Zahlungsabwicklung blockieren. Wenn die E‑Mail‑API ausfällt, sollte der Circuit Breaker nach wenigen schnellen Fehlern öffnen und Aufrufe für eine kurze Cooldown‑Phase stoppen.

Statt E‑Mails inline zu senden, legen Sie einen „Receipt senden“‑Job mit einem Idempotency‑Schlüssel in die Queue (z. B. order_id + email_type). Wenn der Provider down ist, retryt die Queue im Hintergrund und der Kunde sieht trotzdem einen erfolgreichen Kauf.

Ergebnis: weniger Support‑Tickets wegen fehlender Bestätigungen und kein Umsatzverlust durch Checkout‑Fehler aus nicht‑zahlungspflichtigen Gründen.

Nächste Schritte: Über die App ausrollen

Wählen Sie einen Workflow, dessen Ausfall am schlimmsten schmerzt (Checkout, Signup, Abrechnung) und machen Sie ihn zur Referenzintegration. Kopieren Sie dann dieselben Defaults überall.

Eine einfache Rollout‑Reihenfolge:

• Timeouts setzen und schnell fehlschlagen mit einer klaren Fehlermeldung.
• Retries mit Backoff hinzufügen, aber nur für retrybare Fehler.
• Idempotenz hinzufügen, damit Retries nicht doppelt belasten oder doppelt erstellen.
• Circuit Breaker einbauen, damit ein schlechter Provider Ihren Kern‑Workflow nicht blockiert.

Schreiben Sie Ihre Defaults nieder und behalten Sie sie langweilig: ein Connect‑Timeout, ein Request‑Timeout, maximale Retry‑Anzahl, Backoff‑Bereich, Breaker‑Cooldown und Regeln, was retrybar ist.

Führen Sie einen Fail‑Drill durch, bevor Sie auf den nächsten Workflow ausweiten. Erzwingen Sie Timeouts (oder blockieren Sie den Provider in einer Testumgebung) und prüfen Sie, ob der Nutzer eine nützliche Meldung sieht, Fallbacks funktionieren und wartende Retries sich nicht für immer aufstauen.

Wenn Sie schnell neue Produkte bauen, lohnt es sich, diese Zuverlässigkeits‑Defaults in eine wiederverwendbare Vorlage zu gießen. Für Teams, die Koder.ai (koder.ai) nutzen, heißt das oft, Timeout, Retry, Idempotency und Breaker‑Regeln einmal zu definieren und dann dasselbe Muster beim Generieren neuer Services anzuwenden.