401, 403, 429 oder 503: API-Fehler gezielt untersuchen
Authentifizierung, Berechtigungen, Anfragegrenzen und Verfügbarkeit vor einem neuen Versuch unterscheiden.
Auf dieser Seite
Die kurze Antwort
Beginnen Sie mit HTTP-Status und Antwortinhalt. 401 weist auf fehlende oder ungültige Authentifizierung hin, 403 auf verweigerten Zugriff. 429 bedeutet zu viele Anfragen, 503 einen aktuell nicht verfügbaren Dienst.
Zuerst die nötigen Informationen sammeln
Notieren Sie Methode, Endpunkt, Status, Zeitpunkt und eine vorhandene Request-ID. Lesen Sie Fehlertext und relevante Antwortheader. Klären Sie auch den Absender: API-Anwendung, Gateway und Schutzproxy können Anfragen aus unterschiedlichen Gründen ablehnen.
Reproduzieren Sie den Fehler mit einer einzelnen minimalen Anfrage. Vergleichen Sie mit einem funktionierenden Aufruf und ändern Sie jeweils nur einen Faktor. Entfernen Sie Authorization, Cookies und URLs mit Zugangsdaten aus Screenshots und Protokollen. Die Request-ID ist meist geeigneter zur Weitergabe.
Ursache vor dem Wiederholen prüfen
Bei 401 prüfen Sie Zugangsdaten und Authentifizierungsverfahren. Bei 403 prüfen Sie Berechtigungen und Ressource. Dieselbe verbotene Anfrage erneut zu senden behebt die Ursache meist nicht.
401 und 403 getrennt untersuchen
Bei 401 prüfen Sie Vorhandensein, Ablauf und erwartetes Verfahren der Zugangsdaten, etwa Bearer. Eine regelkonforme 401-Antwort enthält WWW-Authenticate. Wenn die API eine Erneuerung unterstützt, erneuern Sie einmal und wiederholen Sie einmal. Eine Endlosschleife behebt keine falschen Zugangsdaten.
Bei 403 prüfen Sie Kontorolle, Ressource und API-Berechtigungen. Ein Konto darf möglicherweise lesen, aber nicht ändern. Auch ein Proxy kann eine IP oder Region blockieren. Ein neuer Token ergänzt nicht automatisch fehlende Rechte; beachten Sie Fehlertext und Dienstregeln.
Wiederholungen begrenzen
Beachten Sie bei 429 oder 503 Retry-After, sofern vorhanden, und verlängern Sie die Wartezeiten. Wiederholen Sie nur sichere Operationen: ein Schreibvorgang mit Zeitüberschreitung könnte bereits erfolgt sein. Protokollieren Sie Anfrage-IDs, keine Geheimnisse.
Retry-After richtig verstehen
429 kann ein Benutzer-, IP- oder gemeinsames Kontingent betreffen. In der beispielhaften Antwort unten bedeutet Retry-After: 30 eine Wartezeit von 30 Sekunden. Der Header kann stattdessen ein HTTP-Datum enthalten; ein echter Client muss auch diese Form berücksichtigen.
Verringern Sie parallele Aufrufe und koordinieren Sie Wiederholungen aller Worker mit demselben Kontingent. Prüfen Sie bei 503 auch Dienst und Gateway. Beachten Sie Retry-After oder verwenden Sie begrenzte wachsende Wartezeiten mit Zufallsanteil und einem Gesamtzeitlimit. Zusätzliche Wiederholungen können eine Überlastung verlängern.
HTTP/1.1 429 Too Many Requests
Retry-After: 30Keine Antwort bedeutet nicht zwingend keine Ausführung
Eine Zahlungs- oder Auftragserstellung kann nach der Annahme durch den Server in ein Timeout laufen. Ein erneuter Aufruf kann ein Duplikat erzeugen, obwohl die erste Antwort ausblieb. Verwenden Sie für Schreibvorgänge die dokumentierte Idempotenzfunktion oder prüfen Sie vorher den Vorgangsstatus. Erfinden Sie keinen nicht unterstützten Header.
Ein brauchbarer Client trennt dauerhafte Berechtigungsprobleme von vorübergehenden Fehlern, begrenzt Versuche und dokumentiert den Abbruchgrund. GET lässt sich meist einfacher wiederholen als POST; maßgeblich bleibt der API-Vertrag. Geben Sie Zeitpunkt, Endpunkt, Status und Request-ID ohne Geheimnisse weiter.
Was Sie prüfen sollten
- Antwortinhalt und Header lesen.
- Prüfen, ob die Operation wiederholt werden darf.
- Versuche begrenzen und Anfrage-IDs aufbewahren.
Geltungsbereich
APIs unterscheiden sich. Deren Dokumentation und Fehlerantwort sind aussagekräftiger als der Statuscode allein.