API-Fehler: richtig behandeln und wiederholen

Eine blinde Wiederholungsschleife ist häufig der Grund, warum eine Integration mit einer fremden API eine kurzfristige Störung nicht übersteht, sondern sie noch verschlimmert: Sie hämmert weiter auf einen bereits ungültigen Schlüssel, verbraucht das Anfragelimit für von vornherein aussichtslose Aufrufe oder bucht im schlimmsten Fall denselben Kauf mehrfach ab. Der richtige Ansatz beginnt nicht mit der Pause zwischen den Versuchen, sondern mit der Klassifizierung der Ursache: Nicht jeder Fehler sollte wiederholt werden, und nicht jede Wiederholung ist sicher.

Drei Kategorien von API-Fehlern

Temporäre Fehler hängen nicht mit dem Inhalt der Anfrage zusammen: Netzwerkabbruch, Verbindungs-Timeout, kurzzeitige Überlastung des Dienstes beim Anbieter. Dieselbe Anfrage mit denselben Parametern funktioniert wenige Sekunden später ganz normal, weil der Defekt im Kanal oder im Zeitpunkt lag und nicht in der Anfrage selbst.

Dauerhafte Fehler sind der umgekehrte Fall: ein ungültiger Zugriffsschlüssel, ein ungültiger Parameter, fehlende Berechtigung für die Operation. Ein solcher Aufruf scheitert beim ersten Versuch genauso wie beim hundertsten, weil die Ursache in der Anfrage selbst oder in der Konfiguration des Kontos liegt. Eine Wiederholung ohne Behebung der Ursache bringt nichts außer einer überflüssigen Zeile im Log.

Geldbezogene Fehler ähneln formal den temporären: zu wenig Guthaben auf dem Konto, keine verfügbare Nummer für das gewünschte Land. Eine erneute Anfrage kann später funktionieren, nach dem Aufladen des Guthabens oder der Aktualisierung des Bestands, doch man darf sie nicht blind wiederholen, erst recht nicht die Abbuchung selbst – die folgenden Abschnitte erklären, warum.

Was sich wiederholen lässt und was nicht

Die Regel ist einfach: Wiederholen lohnt sich nur, was sich allein durch Zeitablauf beheben kann. Ein Netzwerkausfall, ein Timeout, eine 5xx-Antwort oder ein Hinweis auf Überlastung sind Kandidaten für eine automatische Wiederholung nach dem Backoff-Schema. Ein ungültiger Schlüssel, ein fehlerhafter Parameter, eine Ablehnung wegen fehlender Rechte – hier ist eine Wiederholung sinnlos, solange die Ursache nicht manuell beseitigt wurde: Die Einstellung muss korrigiert und der Aufruf einmal erneut gesendet werden, statt eine Schleife laufen zu lassen. Fehlendes Guthaben oder fehlenden Bestand zeigt man der aufrufenden Seite als eigenen Zustand an, und über eine Wiederholung entscheidet die Geschäftslogik oder der Nutzer, nicht ein Timer. Wo im Modell „Kauf nach Aktivierung oder auf Zeit“ häufiger ein Bestandsmangel auftritt, wird im Artikel OTP-Aktivierung versus Nummernmiete erläutert.

Exponential Backoff und der Preis blinder Wiederholung

Exponential Backoff ist eine Pause vor dem nächsten Versuch, die mit jedem Mal länger wird: beispielsweise eine Sekunde, dann zwei, vier, acht – bis zu einer Obergrenze von einigen Versuchen, üblicherweise drei bis fünf, danach wird die Schleife beendet und der Fehler als endgültig weitergegeben. Zur Pause sollte man eine kleine zufällige Streuung hinzufügen, damit viele Clients, die auf dieselbe Störung beim Anbieter gestoßen sind, ihn nicht genau im Moment der Wiederherstellung mit einer synchronen Welle treffen.

Ohne Klassifizierung am Anfang rettet Backoff nichts: Auf eine dauerhafte Ursache angewendet, zieht er nur nutzlose Aufrufe in die Länge, von denen jeder einen Platz im gemeinsamen Limit des Kontos belegt. Solange die Schleife vergeblich auf einen ungültigen Schlüssel hämmert, stoßen nützliche Anfragen desselben Kontos – echte Aktivierungen, Statusabfragen – an dasselbe Limit und werden bereits wegen der Ratenbegrenzung abgelehnt. In der Automatisierung mit parallelen Workern, die im Artikel über Registrierungen über die API behandelt wird, kann ein einziger in der Wiederholungsschleife hängender Prozess das Limit für alle anderen blockieren.

Logs für die Analyse von Vorfällen

Nach einer Störung erfolgt die Analyse anhand des Logs und nicht aus dem Gedächtnis. Deshalb muss genug aufgezeichnet werden, um die Frage „Liegt es am Anbieter oder an unserer Seite“ ohne erneutes Nachstellen des Problems zu beantworten. Mindestumfang: Zeitpunkt des Aufrufs, Endpunkt, Kennung der Anfrage oder Aktivierung, Code und Text der Ablehnung durch den Anbieter, laufende Nummer des Versuchs und Parameter ohne Geheimnisse – Schlüssel und Token gehören nicht ins Log.

Gesondert sollte man nicht nur die Antwort des Anbieters festhalten, sondern auch, wie Ihr Handler die Ursache klassifiziert hat – als temporär, dauerhaft oder geldbezogen. Hat der Klassifikator einen Fehler gemacht und eine dauerhafte Ursache tatsächlich wie eine temporäre wiederholt, ist das nur an einem solchen Eintrag erkennbar, nicht allein am Antwortcode.

Idempotenz bei Geldoperationen: so vermeiden Sie Doppelbuchungen

Ein Timeout sagt nicht eindeutig, ob die Operation auf dem Server ausgeführt wurde: Die Verbindung kann erst nach der Abbuchung abgerissen sein, aber bevor die Antwort den Client erreicht hat. Die Wiederholung einer solchen Anfrage ohne Schutz sieht für die API wie eine neue Operation aus – und führt zu einer doppelten Abbuchung für denselben Kauf.

Ein Idempotenzschlüssel löst das Problem: Der Client erzeugt einmal pro Operation eine eindeutige Kennung und übergibt sie bei jedem Versuch, auch bei Wiederholungen nach einem Timeout. Der Server merkt sich das Ergebnis, das er für diesen Schlüssel geliefert hat, und gibt es bei einem erneuten Aufruf mit demselben Wert zurück, statt die Operation erneut auszuführen. Das ist der einzige sichere Weg, einen Geldaufruf zu wiederholen – ohne Schlüssel bleibt das Risiko einer Doppelabbuchung immer bestehen.

Häufig gestellte Fragen

Muss man den Fehler 429 genauso wiederholen wie ein Timeout?

Ja, aber mit einer längeren Pause: 429 bedeutet keine Störung, sondern ein erschöpftes Anfragelimit, und eine sofortige Wiederholung verlängert nur die Wartezeit für alle. Nehmen Sie den Wert aus dem Antwort-Header, falls der Anbieter ihn liefert, oder beginnen Sie den Backoff gleich mit einer Pause von mehreren Sekunden statt mit einer.

Kann man eine Anfrage zur Abbuchung vom Guthaben bei einem Timeout automatisch wiederholen?

Nicht die Anfrage an sich – nur die Operation mit einem Idempotenzschlüssel. Ein Timeout sagt nicht, ob die Operation vor dem Verbindungsabbruch auf dem Server ausgeführt wurde; die Wiederholung mit demselben Schlüssel ist sicher, weil der Anbieter das Ergebnis der bereits ausgeführten Operation zurückgibt, statt erneut abzubuchen. Ohne Schlüssel riskiert eine solche Wiederholung eine doppelte Zahlung.

Wie viele Versuche sind bei der Wiederholung eines temporären Fehlers sinnvoll?

In der Regel drei bis fünf Versuche mit exponentieller Pause und einer Gesamtobergrenze der Wartezeit von etwa 30-60 Sekunden. Mehr Versuche ändern selten das Ergebnis: Hat sich der Anbieter in diesem Zeitraum nicht erholt, ist das Problem systemisch, und man sollte es eskalieren, statt die Schleife fortzusetzen.

Codes nach Kategorien, den Header für den Idempotenzschlüssel und die Wiederholungsparameter für jeden Endpunkt finden Sie in der API-Dokumentation. Der Empfang von Ereignissen per Webhook, der ebenfalls auf Wiederholungen und Idempotenz beruht, wird im Artikel Webhooks: Codes empfangen ohne Polling behandelt, grundlegende Integrationsszenarien im Beitrag API für die Nummernmiete.