Wie geht man mit API-Rückgaben 401, 403 und 429 um? Leitfaden zur Fehlerbehebung bei Authentifizierung, Berechtigungen und Ratenbegrenzung

Beim Aufrufen einer API sind 401 Unauthorized, 403 Forbidden und 429 Too Many Requests die drei häufigsten Fehlerarten.

Sie gehören alle zu den 4xx-Client-Fehlern, aber die Lösungsansätze sind völlig unterschiedlich:

• 401: Authentifizierung fehlgeschlagen — der Server kann nicht bestätigen, „wer du bist“
• 403: Zugriff verweigert — der Server versteht die Anfrage, erlaubt ihre Ausführung aber nicht
• 429: Zu viele Anfragen — Aufrufgeschwindigkeit oder Nutzung überschreitet die Begrenzung

Wenn Fehlerarten nicht unterschieden werden und direkt Wiederholungsversuche erfolgen, lässt sich das Problem nicht nur nicht lösen, sondern es kann auch zu einem Retry-Sturm kommen oder sogar dazu führen, dass die Schnittstelle weiter eingeschränkt wird.

Dieser Artikel erläutert anhand von Checklisten zur Fehlerbehebung, curl-Befehlen und Node.js-Code, wie bei diesen drei Fehlerarten vorzugehen ist.

¶ 401, 403 und 429 auf einen Blick

Statuscode	Kernbedeutung	Häufige Ursachen	Sollte sofort erneut versucht werden
401 Unauthorized	Gültige Authentifizierungsdaten fehlen	API Key falsch, Token abgelaufen, falsches Format des Authentifizierungs-Headers	Sollte nicht unverändert wiederholt werden
403 Forbidden	Der Server verweigert die Verarbeitung der Anfrage	Unzureichende Berechtigungen, IP- oder Regionsbeschränkungen, Ressourcenrichtlinien, WAF-Blockierung	Normalerweise nicht
429 Too Many Requests	Anfragen überschreiten Raten- oder Kontingentgrenzen	Zu hohe Parallelität, QPS-Limit überschritten, Kontingent aufgebraucht	Nach einer Wartezeit erneut versuchen

Zu beachten ist, dass die englische Bezeichnung von 401 zwar Unauthorized lautet, es bei der praktischen Fehlerbehebung jedoch besser als „nicht authentifiziert“ verstanden wird; 403 steht hingegen üblicherweise im Zusammenhang mit Autorisierung oder Zugriffsrichtlinien.

¶ I. 401 Unauthorized: Zuerst die Authentifizierungsdaten prüfen

HTTP 401 Unauthorized bedeutet, dass der Anfrage gültige Authentifizierungsdaten fehlen, die für die Zielressource erforderlich sind. Eine standardmäßige 401-Antwort teilt dem Client normalerweise über den Response-Header WWW-Authenticate mit, welches Authentifizierungsschema der Server erwartet.

¶ Häufige Ursachen

1. Der Request-Header Authorization wurde nicht gesendet
2. API Key oder Access Token wurde falsch eingegeben
3. Token ist abgelaufen oder wurde widerrufen
4. Falsches Authentifizierungsschema, beispielsweise fehlt Bearer
5. Umgebungsvariablen wurden nicht korrekt geladen
6. Ein Schlüssel aus der falschen Umgebung wurde verwendet
7. Beim Weiterleiten der Anfrage durch einen Proxy oder ein Gateway geht der Authentifizierungs-Header verloren
8. Die Zeitabweichung zwischen Client und Server ist zu groß, wodurch die Signatur ungültig wird

¶ Häufige Fehler

Die Schnittstelle verlangt ein Bearer Token:

Authorization: Bearer YOUR_ACCESS_TOKEN

Der Client sendet jedoch:

Authorization: YOUR_ACCESS_TOKEN

Oder es wird fälschlicherweise geschrieben:

Authentication: Bearer YOUR_ACCESS_TOKEN

Beide Fälle können 401 zurückgeben.

¶ Fehlerbehebung mit curl

Nicht gleich zu Beginn nur den Response-Body ansehen. Mit -i werden gleichzeitig Statuscode und Response-Header geprüft:

curl -i "https://api.example.com/v1/profile" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Accept: application/json"

Folgende Punkte besonders prüfen:

• Ob Authorization tatsächlich gesendet wurde
• Ob das Authentifizierungsschema korrekt ist
• Ob vor oder nach dem Token Leerzeichen oder Zeilenumbrüche vorhanden sind
• Was WWW-Authenticate zurückgibt
• Ob der Response-Body Fehlermeldungen wie invalid_token, expired_token usw. enthält

Für einen detaillierteren Request-Ablauf kann Folgendes verwendet werden:

curl -v "https://api.example.com/v1/profile" \
  -H "Authorization: Bearer $API_TOKEN"

Hinweis: Debug-Logs können Tokens enthalten. Vollständige Logs nicht direkt in öffentlichen Issues, Gruppenchats oder Tickets veröffentlichen.

¶ Sollte 401 erneut versucht werden?

Nicht wiederholt mit denselben ungültigen Anmeldedaten versuchen.

Empfohlener Ablauf:

1. Prüfen, ob die Anfrage Authentifizierungsinformationen enthält
2. Prüfen, ob das Token abgelaufen, widerrufen oder falsch kopiert wurde
3. Falls Refresh Token unterstützt werden, das Zugriffstoken einmal aktualisieren
4. Mit dem neuen Token einmal erneut versuchen
5. Falls weiterhin 401 zurückgegeben wird, Wiederholungsversuche stoppen und den Fehler protokollieren

Bei Verwendung eines festen API Keys sollte der Schlüsselstatus geprüft oder ein gültiger Schlüssel ersetzt werden, anstatt Wiederholungsversuche in einer Schleife auszuführen.

¶ II. 403 Forbidden: Die Authentifizierung kann erfolgreich sein, aber die Anfrage wird dennoch abgelehnt

403 Forbidden bedeutet, dass der Server die Anfrage bereits verstanden hat, ihre Verarbeitung jedoch verweigert. Bei typischen Berechtigungsfehlern wird das Problem selbst durch eine erneute Authentifizierung nicht automatisch gelöst; wenn die Anfrage oder die Berechtigungskonfiguration nicht geändert wird, schlagen wiederholte Anfragen normalerweise weiterhin fehl.

¶ Häufige Ursachen

• Dem aktuellen Konto oder Schlüssel fehlen erforderliche Berechtigungen
• Der Scope des Tokens ist unzureichend
• Auf eine Ressource zugegriffen, die nicht zum aktuellen Projekt oder Mandanten gehört
• Die Quell-IP befindet sich nicht auf der Whitelist
• Die Region der Anfragequelle unterliegt Einschränkungen
• WAF, Firewall oder Anti-Missbrauchssystem blockiert die Anfrage
• Konto, Projekt oder Ressource wurde deaktiviert
• Die Schnittstelle ist nur für bestimmte Tarife oder Rollen verfügbar
• Die Signatur ist gültig, aber der Ressourcenbereich in der Signatur stimmt nicht überein
• Im Browser-Kontext gelten Einschränkungen durch CSRF-, Origin- oder Referer-Richtlinien

¶ Der Unterschied zwischen 401 und 403

Mit zwei Sätzen lässt sich schnell unterscheiden:

• 401: Der Server kann nicht bestätigen, wer du bist
• 403: Der Server kennt oder versteht deine Identität und Anfrage, erlaubt dir dies aber nicht

Beispielsweise ruft ein gewöhnliches Mitglied mit einem gültigen Token die Schnittstelle „Organisation löschen“ auf:

curl -i -X DELETE \
  "https://api.example.com/v1/organizations/org_123" \
  -H "Authorization: Bearer $API_TOKEN"

Wenn das Token gültig ist, das Konto jedoch kein Organisationsadministrator ist, könnte der Server Folgendes zurückgeben:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "insufficient_permissions",
  "message": "Administrator role is required."
}

¶ Reihenfolge bei der 403-Fehlerbehebung

¶ 1. Response-Body lesen

Vorrangig nach Fehlercodes, fehlenden Rollen oder Berechtigungen, erforderlichen Scopes, abgelehnten Ressourcen-IDs sowie Hinweisen zu IP-, Regions- oder Sicherheitsrichtlinien suchen.

¶ 2. Token-Scope prüfen

Beispielsweise kann das Lesen von Daten nur data:read benötigen, während das Erstellen von Daten data:write erfordern kann. Ein gültiges Token bedeutet nicht, dass alle Berechtigungen vorhanden sind.

¶ 3. Ressourcenzugehörigkeit prüfen

Bestätigen, dass Projekt-ID, Organisations-ID, Mandanten-ID, Benutzer-ID, Region oder Umgebung und die aktuellen Anmeldedaten zum selben Konto oder Berechtigungsbereich gehören.

¶ 4. Netzwerk- und Sicherheitsrichtlinien prüfen

Wenn der Code lokal normal läuft, aber nach der Bereitstellung 403 zurückgibt, sollten insbesondere die Server-Ausgangs-IP, die IP-Whitelist, die Proxy-Konfiguration, das CDN, die WAF, die geografische Herkunft der Anfrage und die zugehörigen Anfrage-Header überprüft werden.

¶ Ziehen Sie nicht allein aufgrund des Statuscodes Schlussfolgerungen

Die API-Implementierungen in der Praxis sind nicht unbedingt vollständig einheitlich. Manche Plattformen geben bei ausgelöster Ratenbegrenzung möglicherweise 403 statt 429 zurück. Beispielsweise kann die GitHub REST API beim Überschreiten des Ratenlimits 403 oder 429 zurückgeben und den Einschränkungsstatus über Antwort-Header wie x-ratelimit-remaining, x-ratelimit-reset oder retry-after erläutern.

Daher sollten bei einem 403 auch folgende Punkte umfassend überprüft werden:

• Geschäftlicher Fehlercode im Antworttext
• Retry-After
• X-RateLimit-Remaining
• X-RateLimit-Reset
• Offizielle Dokumentation der Plattform

¶ Sollte 403 erneut versucht werden?

Bei 403 aufgrund unzureichender Berechtigungen, IP-Einschränkungen oder Ressourcenrichtlinien ist ein unveränderter erneuter Versuch bedeutungslos.

Der richtige Ansatz besteht darin, Berechtigungen oder Token Scopes zu ändern, das richtige Konto oder Projekt zu verwenden, Whitelists und Sicherheitsrichtlinien anzupassen, die Ressourcen-ID zu korrigieren und zu bestätigen, ob der Dienst oder Tarif diese Schnittstelle unterstützt. Nur wenn die Plattform ausdrücklich erklärt, dass dieser 403 tatsächlich eine temporäre Ratenbegrenzung darstellt, sollte gemäß den Regeln zur Ratenbegrenzung gewartet und anschließend erneut versucht werden.

¶ Drei, 429 Too Many Requests: Zuerst verlangsamen, dann erneut versuchen

429 Too Many Requests bedeutet, dass der Client innerhalb eines Zeitraums zu viele Anfragen gesendet hat, also eine Ratenbegrenzung ausgelöst wurde. Der Server kann dem Client über Retry-After mitteilen, wie lange er vor einem erneuten Versuch warten soll.

¶ Häufige Ursachen

• Zu viele Anfragen innerhalb kurzer Zeit
• Zu hohe Anzahl gleichzeitiger Aufgaben
• Mehrere Dienste teilen sich denselben API Key
• Der Wiederholungs-Code verfügt über keinen Warte-Mechanismus
• Geplante Aufgaben werden gleichzeitig gebündelt ausgeführt
• Anfragen werden nicht zwischengespeichert und dieselben Daten wiederholt abgerufen
• Das Kontingent eines einzelnen Kontos, einer IP oder eines Projekts ist erschöpft
• Nutzungs- oder Guthabenbeschränkungen des Tarifs

¶ Prüfen Sie zuerst die Antwort-Header

curl -i "https://api.example.com/v1/resources" \
  -H "Authorization: Bearer $API_TOKEN"

Besonders beachten:

Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1710000000

Die Namen der Antwort-Header können je nach Plattform unterschiedlich sein; maßgeblich ist die Dokumentation der Plattform.

¶ Retry-After korrekt behandeln

Die zwei häufigen Formate von Retry-After sind Sekunden oder ein HTTP-Datum:

Retry-After: 30

Retry-After: Wed, 21 Oct 2026 07:28:00 GMT

Der Client sollte möglichst beide Formate unterstützen.

¶ Warum kann nicht sofort erneut versucht werden?

Wenn unmittelbar nach einer Ratenbegrenzung erneut versucht wird, unterliegt die neue Anfrage weiterhin der Ratenbegrenzung; mehrere Clients können zudem gleichzeitig erneut versuchen und einen „Thundering Herd“ bilden. Ein sicherer Ansatz ist:

1. Vorrangig Retry-After einhalten
2. Wenn keine eindeutige Wartezeit vorhanden ist, exponentiellen Backoff verwenden
3. Der Wartezeit zufälligen Jitter hinzufügen
4. Maximale Anzahl von Wiederholungen festlegen
5. Nach Erreichen der Obergrenze einen eindeutigen Fehler zurückgeben

¶ Node.js: 429 sicher behandeln

Das folgende Beispiel verwendet das integrierte fetch von Node.js und analysiert vorrangig Retry-After; falls der Server diesen Antwort-Header nicht bereitstellt, wird exponentieller Backoff mit zufälligem Jitter verwendet.

const sleep = (ms) =>
  new Promise((resolve) => setTimeout(resolve, ms));

function parseRetryAfter(value) {
  if (!value) return null;

  const seconds = Number(value);
  if (Number.isFinite(seconds) && seconds >= 0) {
    return seconds * 1000;
  }

  const timestamp = Date.parse(value);
  if (!Number.isNaN(timestamp)) {
    return Math.max(0, timestamp - Date.now());
  }

  return null;
}

async function fetchWithRetry(url, options = {}, config = {}) {
  const {
    maxRetries = 3,
    baseDelayMs = 1000,
    maxDelayMs = 30_000,
  } = config;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    if (attempt === maxRetries) {
      throw new Error(
        `请求持续受到限流，已达到最大重试次数：${maxRetries}`
      );
    }

    const retryAfterMs = parseRetryAfter(
      response.headers.get("retry-after")
    );

    const backoffCap = Math.min(
      maxDelayMs,
      baseDelayMs * 2 ** attempt
    );

    const jitterMs = Math.floor(Math.random() * backoffCap);
    const delayMs = retryAfterMs ?? jitterMs;

    console.warn(
      `收到 429，第 ${attempt + 1} 次等待 ${delayMs}ms 后重试`
    );

    await sleep(delayMs);
  }

  throw new Error("请求失败");
}

Aufrufbeispiel:

const response = await fetchWithRetry(
  "https://api.example.com/v1/resources",
  {
    headers: {
      Authorization: `Bearer ${process.env.API_TOKEN}`,
      Accept: "application/json",
    },
  },
  {
    maxRetries: 3,
    baseDelayMs: 1000,
    maxDelayMs: 30_000,
  }
);

if (!response.ok) {
  const errorBody = await response.text();
  throw new Error(`API 请求失败：${response.status} ${errorBody}`);
}

const data = await response.json();
console.log(data);

¶ Beim Wiederholen von POST-Anfragen muss auch die Idempotenz berücksichtigt werden

Nicht alle Anfragen eignen sich für automatische Wiederholungen. Leseanfragen wie GET und HEAD lassen sich normalerweise eher sicher wiederholen. Bei POST-Anfragen zum Erstellen von Bestellungen, Abbuchen oder Senden von Nachrichten kann der Client die Übermittlung möglicherweise bereits erfolgreich abgeschlossen haben, aber wegen einer Netzwerkunterbrechung keine Antwort erhalten haben. Ein direkter erneuter Versuch kann dann doppelte Vorgänge verursachen.

Falls die Plattform dies unterstützt, sollte für Schreibvorgänge ein Idempotenzschlüssel gesetzt werden:

curl -i -X POST "https://api.example.com/v1/orders" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20260331-0001" \
  -d '{
    "product_id": "prod_123",
    "quantity": 1
  }'

Der Name des Anfrage-Headers und die Gültigkeitsdauer des Idempotenzschlüssels werden von der jeweiligen Plattform festgelegt; die entsprechende API-Dokumentation sollte konsultiert werden.

¶ Checkliste zur Fehlerbehebung in der Produktionsumgebung

¶ 401 erhalten

• Ob die Anfrage einen Authentifizierungs-Header enthält
• Ob das Authentifizierungsschema wie Bearer korrekt ist
• Ob das Token abgelaufen, widerrufen oder fehlerhaft kopiert wurde
• Ob der Schlüssel der richtigen Umgebung verwendet wird
• Ob ein Proxy oder Gateway den Authentifizierungs-Header entfernt hat
• Ob die Client-Zeit korrekt ist
• Ob ein einmaliges Aktualisieren des Tokens sicher möglich ist

¶ 403 erhalten

• Ob das Token über die erforderlichen Scopes verfügt
• Ob das aktuelle Konto über die erforderliche Rolle verfügt
• Ob die Ressource zum aktuellen Projekt oder Mandanten gehört
• Ob die ausgehende IP auf der Whitelist steht
• Ob Einschränkungen durch Region, WAF oder Sicherheitsrichtlinien bestehen
• Ob der Antwortkörper eindeutig auf Berechtigungen oder Ratenbegrenzung hinweist
• Ob in den Antwortheadern Informationen zur Ratenbegrenzung vorhanden sind

¶ 429 erhalten

• Ob Retry-After ausgelesen wurde
• Ob Antwortheader im Zusammenhang mit Ratenbegrenzung überprüft wurden
• Ob exponentielles Backoff und zufälliger Jitter verwendet werden
• Ob eine maximale Anzahl von Wiederholungsversuchen festgelegt wurde
• Ob die Parallelität begrenzt wird
• Ob Ergebnisse doppelter Abfragen zwischengespeichert werden
• Ob Anfragen zusammengeführt oder stapelweise gesendet werden können
• Ob das Paketkontingent oder die Nutzungsobergrenze des Kontos erreicht wurde

¶ Welche Diagnoseinformationen sollten aufgezeichnet werden?

Es wird empfohlen, in den Logs die Anfragezeit, den API-Hostnamen und -Pfad, die HTTP-Methode, den Statuscode, den geschäftlichen Fehlercode, request-id oder trace-id, Retry-After, das verbleibende Kontingent der Ratenbegrenzung und die Rücksetzzeit, die Anzahl der Wiederholungsversuche sowie die tatsächliche Wartezeit aufzuzeichnen.

Zeichnen Sie jedoch nicht den vollständigen API Key, den vollständigen Access Token, Refresh Token, Benutzerpasswörter oder sensible personenbezogene Informationen im Anfragekörper auf.

¶ Die abschließende Entscheidungsregel

401: Zuerst die Anmeldedaten korrigieren, nicht mit dem alten Token erneut versuchen.
403: Zuerst Berechtigungen oder Richtlinien korrigieren, die Anfrage nicht unverändert wiederholen.
429: Die Wartezeit respektieren, Backoff anwenden, Geschwindigkeit reduzieren, Parallelität begrenzen.

Der Statuscode ist nur der Einstieg in die Fehlerbehebung, nicht die ganze Antwort. Eine zuverlässige Vorgehensweise besteht darin, gleichzeitig den HTTP-Statuscode, den geschäftlichen Fehlercode im Antwortkörper, relevante Antwortheader, die Plattformdokumentation, die Anfrage-ID und Serverprotokolle zu berücksichtigen und aus „die Schnittstelle meldet einen Fehler“ einen beobachtbaren, wiederherstellbaren und wartbaren technischen Mechanismus zu machen.

¶ Referenzmaterialien

• RFC 9110: HTTP-Semantik
• RFC 6585: Zusätzliche HTTP-Statuscodes
• MDN: 401 Nicht autorisiert
• MDN: 403 Verboten
• GitHub REST API-Ratenbegrenzungen
• AWS SDK-Wiederholungsverhalten