Fehlerbehandlung
Teil von API-Limits und Leistung
Gedrosselte API-Anfragen kontrolliert wiederholen
Bei API-Drosselung Wartehinweise auswerten, Versuche begrenzen und unklare Schreibwirkungen vor einem Retry prüfen.
Nach einer Drosselungsantwort pausieren Sie Aufrufe, die dasselbe betroffene Budget belasten. Lesen Sie die Wartevorgabe der konkreten API und wiederholen Sie nur Anfragen, deren erneute Ausführung zulässig ist.
Begrenzen Sie Versuche und die Frist des gesamten Vorgangs; sofortige Wiederholungen können die Belastung erhöhen.
Die Antwort der API auswerten
Bei 429 meldet ein Dienst zu viele Anfragen. Ein vorhandener Retry-After-Header kann eine Wartezeit in Sekunden vorgeben. Ein Client muss den gelieferten Wert auswerten und die angegebene Wartezeit berücksichtigen.
Fehlt eine Wartevorgabe, ist eine begrenzte Rückfallregel mit steigenden, leicht gestreuten Wartezeiten sinnvoll. Dienstspezifische Vorgaben gehen vor.
Je nach API können Drosselungsantworten unterschiedliche Statuscodes und Wartehinweise enthalten. Werten Sie die dokumentierten Angaben des jeweiligen Dienstes aus und verlassen Sie sich nicht allein auf 429 oder einen stets gleichen Timer.
Microsoft Graph empfiehlt, bei gedrosselten Aufrufen den Retry-After-Header zu beachten und sofortige Wiederholungen zu vermeiden. Werten Sie die Drosselungsantwort der API aus, bevor Sie einen weiteren Versuch planen.
Versuche und Frist zusammenführen
Befund / Nächste Entscheidung
- Noch nicht gesendet
- Platz im relevanten gemeinsamen Anfragebudget abwarten.
- Eindeutig gedrosselt
- Frühestens nach der maßgeblichen Wartezeit erneut zulassen.
- Erneut gedrosselt
- Neue Vorgabe auswerten und Versuchszahl sowie Gesamtfrist prüfen.
- Frist oder Versuchslimit erreicht
- Fall sichtbar offen halten und nach der vereinbarten Regel übergeben.
- Wirkung einer Schreibanfrage unklar
- Zielzustand klären, bevor dieselbe Aktion nochmals angefordert wird.
Diese Zustände sind ein möglicher Entwurf für den eigenen Workflow. Halten Sie je Fall Kennung, Operation, Versuchszahl, nächste zulässige Zeit und bekannten Ergebnisstand fest.
Teilen mehrere Worker ein Limit, müssen sie die betroffene Pause gemeinsam berücksichtigen.
Schritte zur kontrollierten Wiederholung nach API-Drosselung
- Wartevorgabe einhaltenWarten Sie mindestens die im `Retry-After`-Header angegebene Zeit, falls vorhanden.
- Zustand dokumentierenSpeichern Sie Operation, Versuchszahl, nächste zulässige Zeit und Ergebnisstand.
Bei Schreibanfragen den Ausgang klären
Ein erneuter Leseaufruf ist meist leichter zu beurteilen als eine Anlage oder ein Versand. Nach einer eindeutig abgewiesenen Schreibanfrage kann ein späterer Versuch zulässig sein. Ging jedoch die Antwort auf eine möglicherweise wirksame Anfrage verloren, beweist das keinen Fehlschlag.
Prüfen Sie, ob die Ziel-API eine stabile Referenz, eine Ergebnisabfrage oder einen für diese Operation dokumentierten Idempotenzmechanismus bietet. Bleibt der Ausgang unklar, darf ein automatischer Retry keine zweite fachliche Wirkung riskieren.
Für einen Prüffall sollten eine erste und eine erneute Drosselung, eine fehlende Wartevorgabe, eine abgelaufene Vorgangsfrist und eine verlorene Schreibantwort jeweils einen eindeutig festgelegten nächsten Zustand haben.
Prüfliste vor Wiederholung einer Schreibanfrage
- Stabile Referenz verfügbar?Prüfen Sie, ob die API eine eindeutige ID oder Referenz zurückgibt.
- Ergebnisabfrage möglich?Können Sie den Erfolg über einen separaten Leseaufruf prüfen?
- Idempotenzmechanismus dokumentiert?Gibt es eine idempotente Operation (z. B. eindeutige Request-ID)?
- Antwort verloren?Wenn ja: Kein automatisches Retry ohne Klarstellung des Ausgangs.
