HTTP-Fehlercodes, die Sie tatsächlich treffen — 301 vs. 302, 401 vs. 403 und das 5xx-Feld

Sie haben einen Redirect versandt, und er war der falsche Typ. Jetzt haben alle Browser, die ihn vor Ihnen erreicht haben, ihn dauerhaft gespeichert, und der einzige Weg, ihn zu beheben, ist, auf Ablauf der Cachezeit zu warten oder Benutzern zu verlangen, ihre Browsergeschichte zu löschen. Das ist ein 301.

Dies ist kein Statuscode-Wörterbuch – es gibt bereits viele davon. Dies ist die Anleitung, die Sie benötigen, nachdem Sie die Tabelle gelesen und dennoch den falschen Code versandt haben. Wir gehen durch die Fälle, die tatsächlich Fehler verursachen: dauerhafte Caches, wenn Sie temporäre benötigt haben, Auth-Fehler, die Informationen preisgeben, Rate-Limit-Responsen, die nicht korrekt behandelt werden, und Gateway-Timeouts, die auf die falsche Schicht zeigen.

301 vs 302 vs 307 vs 308: Die Redirect-Matrix

Der Fehler, den jeder mindestens einmal macht: Sie verwenden 301 Moved Permanently beim Testen einer URL-Neuorganisation. Es funktioniert. Sie gehen weiter. Dann machen Sie eine weitere Neugestaltung. Und nun wird ein Teil Ihrer Benutzer – jeder, der vor der zweiten Änderung besucht hat – dauerhaft an die alte Zieladresse weitergeleitet, und dieser Redirect ist bereits in ihrem Browser gespeichert.

301 ist dauerhaft und speichert aggressiv ab. Browsers legen den TTL des gespeicherten Redirects praktisch auf unendlich fest, es sei denn, Sie haben einen Cache-Control Header gesetzt. Es gibt keine programmierte Möglichkeit, ihn aus dem Browser zu löschen. Wenn Sie noch Ihre URL-Struktur ausarbeiten, verwenden Sie 302.

Das Problem der Methode-Erfassung ist ein anderes Tier. Wenn ein Browser einen 301 oder 302 verfolgt, kann er möglicherweise (und in der Praxis fast immer) einen POST auf einen GET herabstufen. Dies ist technisch eine Verletzung des ursprünglichen HTTP/1.0-Spezifikations, aber Browser haben es so lange normalisiert, dass RFC 7231 es als Standardverhalten anerkennt. Wenn Sie einen POST-Redirect durchführen – zum Beispiel nach einer Formabgabe – und die Methode erhalten müssen, benötigen Sie 307 oder 308.

Code	Dauerhaft?	Methode beibehalten?	Verwenden Sie es für
301	Ja	Nein (POST → GET)	Dauerhafte URL-Wechsel, bei denen GET nach dem Redirect ausreichend ist
302	NEIN	Nein (POST → GET)	Temporäre Redirects, Feature-Flags, A/B-Tests
307	NEIN	Ja	Temporäre Redirects, bei denen die Methode beibehalten werden muss
308	Ja	Ja	Dauerhafte Redirects, bei denen die Methode beibehalten werden muss

Die Unterstützung von 308 ist jetzt solide – Chrome, Firefox, Safari und Edge behandeln es korrekt. Die Besonderheit: Einige ältere API-Klienten und HTTP-Bibliotheken folgen 308 noch nicht korrekt, daher sollten Sie bei Redirects von maschinell-maschinell-Verkehr und wenn weder der Klient noch seine HTTP-Bibliothek unter Ihrer Kontrolle sind, dies explizit testen.

401 vs 403: Auth vs Authz

401 bedeutet „Sie haben sich nicht identifiziert.“ Die Spezifikation erfordert, dass ein WWW-Authenticate Header dem Client mitteilt, wie er sich authentifizieren soll. Es ist der richtige Code, wenn es keine gültige Sitzung, kein Token oder ein abgelaufenes Token gibt.

403 bedeutet „Ich weiß, wer Sie sind, und die Antwort ist nein.“ Der Benutzer ist authentifiziert, hat aber keine Berechtigung. Die Rückgabe von 403 bei einem abgelaufenen Token ist falsch – das ist ein 401. Die Rückgabe von 401 bei einem gültigen, aber nicht ausreichend berechtigten Antrag ist ebenfalls falsch und schlimmer noch, es verweist falsch auf die Authentifizierung: Sie suchen nach fehlenden Anmeldedaten, während das echte Problem in der Rolle liegt.

Der Sicherheitsargument für die Rückgabe von 404 anstatt 403 ist echt. Wenn Ihre API 403 bei GET /admin/userszurückgibt, haben Sie einfach jedem Angreifer mitgeteilt, dass der Endpoint existiert und dass er höhere Berechtigungen benötigt, um ihn zu erreichen. Die Rückgabe von 404 enthüllt keine Informationen über die Existenz des Ressourcen. Es ist eine Entscheidung: 403 ist technisch korrekt und einfacher zu debuggen; 404 ist die sichere Wahl für sensible Endpunkte, bei denen die Enumerierbarkeit wichtig ist.

429: Rate Limiting ist nutzlos ohne Retry-After

Eine 429-Antwort ohne einen Retry-After Header ist ein schwarzer Kasten. Der Client weiß, dass er rate-limitet wurde. Er weiß nicht, ob er 100ms oder 24 Stunden warten soll. Die meisten Client-Implementierungen versuchen entweder sofort zu wiederholen (was Ihr Rate-Limiter überlastet) oder geben auf.

Retry-After nimmt entweder eine ganze Zahl (Anzahl der Sekunden, die gewartet werden) oder ein HTTP-Datum (die Zeit, an der er erneut versuchen soll):

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1749254400

Der X-RateLimit-* Headers sind nicht in irgendeinem RFC enthalten – sie sind eine de facto-Standard von GitHubs API, die von allen kopiert wurde. Fügen Sie sie zusammen mit Retry-Afterhinzu. Das Trio aus Limit/Remaining/Reset zeigt dem Client, wo er steht, bevor er die Grenze erreicht, was nützlicher ist als nur zu wissen, dass er die Grenze erreicht hat.

Eines der Wichtigen zu nennen: Retry-After ist ebenfalls gültig bei 503-Antworten und bedeutet genau das gleiche – „warten Sie bitte X Sekunden.“ Wenn Ihr Dienst für einen Wartungszeitraum vorübergehend nicht verfügbar ist, senden Sie eine 503 mit Retry-After anstatt nur Verbindungen abzuschneiden.

503 vs 504: Wo liegt der Fehler?

Diese beiden sehen ähnlich aus, zeigen aber auf völlig unterschiedliche Fehlgeschichten, und die Verwechslung führt in die falsche Richtung beim Debuggen.

503 Service Unavailable bedeutet, dass der Server, den Sie erreicht haben, derzeit nicht in der Lage ist, die Anfrage zu verarbeiten – er ist überlastet, in Wartungsmodus oder eine Backend-Abhängigkeit ist ausfallen. Der Server selbst hat eine Antwort gegeben; er lehnt die Arbeit ab.

504 Gateway Timeout bedeutet, dass ein Proxy oder Gateway (Ihr Load Balancer, nginx, API Gateway, CDN) versucht hat, einen upstream-Server zu erreichen und keine Antwort in der Zeit erhalten hat. Der Server, den Sie erreicht haben, ist aktiv. Das hinterliegende System antwortet nicht.

In der Praxis: Wenn Sie hinter nginx sind und Ihr Anwendungsserver (Node, Rails, Django, was auch immer) abstürzt, erhalten Sie 502 Bad Gateway – nginx hat eine Antwort erhalten, aber sie war schlecht. Wenn der Anwendungsserver komplett nicht antwortet, erhalten Sie 504. Wenn Sie ausdrücklich einen Fehler aus der Anwendungsschicht zurückgeben, erhalten Sie 503. Die Unterscheidung spielt bei der Fehleranalyse eine Rolle: 504 bedeutet, schauen Sie sich das upstream-System, Ihre Timeout-Konfiguration und Ihr Netzwerk an. 503 bedeutet, schauen Sie sich die Anwendung selbst an.

422 vs 400: Validierungsfehler haben ihren eigenen Code

400 Bad Request dient für Anfragen, die vom Server nicht verarbeitet werden können – falsch formatierte JSON, ungültige Query-String-Syntax, fehlende erforderliche Header. Es ist ein strukturelles Problem.

422 Unprocessable Entity dient für Anfragen, die vom Server verstanden wurden, aber nicht verarbeitet werden können, weil die Daten die Validierung verletzen – ein Zeitraum, bei dem der Beginn nach dem Ende liegt, ein E-Mail-Feld mit einer ungültigen Adresse, ein Quantitätsfeld, das negativ ist. Die Anfrage war syntaktisch korrekt. Die Semantik war falsch.

Die meisten APIs fassen beide in 400 zusammen und verstecken die Validierungsdetails im Antworttext. Das funktioniert, aber es macht die Fehlerbehandlung auf der Clientseite schwieriger: Client müssen den Text analysieren, um zu wissen, ob es ein Parsings- oder ein Validierungsproblem ist. Die Verwendung von 422 für Validierungsfehler ermöglicht es den Clients, auf den Statuscode zu vertrauen. Rails hat das seit Ewigkeiten richtig gemacht; die JSON:API-Spezifikation legt 422 für Validierungsfehler fest.

Die eine Nuance: 422 ist in WebDAV (RFC 4918) definiert, nicht im Kern-HTTP-Spezifikation. In der Praxis spielt das keine Rolle – jeder HTTP-Client und Server behandelt es gut – aber Sie werden gelegentlich einen Pedant treffen, der behauptet, Sie sollten 400 verwenden. Sie sind nicht falsch, genau. Aber 422 ist spezifischer und weit verbreitet verstanden.

204 vs 200 mit leerem Körper: Ein ist korrekt für DELETE

Wenn ein DELETE erfolgreich ist, ist die richtige Antwort 204 No Content – nicht 200 mit leerem Körper, und nicht 200 mit {"success": true}.

204 ist die explizite Nachricht, dass „das erfolgreich war und es gibt absichtlich keinen Antworttext.“ Ein 200 mit leerem Körper ist technisch gültig, aber es ist unklar – die Client wissen nicht, ob der Körper ursprünglich vorhanden war und verloren gegangen ist, oder ob die Abwesenheit absichtlich ist. 204 beseitigt die Unklarheit.

Die gleiche Logik gilt für PUT und PATCH, wenn Sie kein aktualisiertes Objekt zurückgeben. Wenn Ihre API das aktualisierte Objekt nach einem PATCH zurückgibt, verwenden Sie 200. Wenn nicht, verwenden Sie 204. Verwenden Sie nicht 200 mit einem leeren Körper – das ist 204 in einem Kostüm. {} oder null Ein kleiner Hinweis:

204 darf kein Nachrichtenfeld enthalten nach RFC 9110. Wenn Sie 204 zurückgeben und versehentlich ein Feld enthalten (einige Frameworks lassen das zu), werden einige HTTP-Client es problemlos verarbeiten, andere nicht. Entfernen Sie das Feld in Ihrem Antworthandler, nicht nur in Ihrem Absicht. Schnelle Referenz: Die Codes, die brennen und warum

Gängiger Fehler

Code	Bedeutung	Fix	Dauerhafte Weiterleitung
301	Verwendung während des Tests – jetzt ist es dauerhaft gespeichert	Verwenden Sie 302, bis die Weiterleitung als dauerhaft bestätigt ist	Temporäre Weiterleitung
302	POST wird beim Folgen auf GET herabgestuft	Verwenden Sie 307, wenn die Methode beibehalten werden muss	Temporäre Weiterleitung (methode-sicher)
307	Verwechselt mit 302	Verwenden Sie 307, wenn POST/PUT/PATCH temporär weitergeleitet werden	Dauerhafte Weiterleitung (methode-sicher)
308	Übersprungen in Gunst von 301	Verwenden Sie 307 anstatt 301, wenn die Methode wichtig ist	Falsche Anfrage (parsenfehler)
400	Verwendet für Validierungsfehler	Verwenden Sie 422 für semantische Validierungsfehler	Nicht authentifiziert
401	Zurückgegeben, wenn der Benutzer keine Berechtigung hat (sollte 403 sein)	Rückgabe von 401 nur dann, wenn die Anmeldeinformationen fehlen oder abgelaufen sind	Zurückgegeben anstatt 404 für sicherheitskritische Endpunkte
403	Verbotene	Betrachten Sie 404, wenn die Verdeckung der Existenz von Endpunkten wichtig ist	Unverarbeitbar
422	Zusammengefasst in 400	Verwenden Sie 422 für Validierungsfehler, bei denen der Körper parsbar war	Rate-limitiert
429	Kein Retry-After-Header	Fügen Sie Retry-After + X-RateLimit-* Headers immer hinzu	Dienst nicht verfügbar
503	Verwechselt mit 504	Verwenden Sie es, wenn der erreichte Server die Anfrage nicht verarbeiten kann	Gateway Timeout
504	Verwechselt mit 503	Untersuchen Sie das upstream-System, nicht den Gateway	Kein Inhalt
204	200 mit leerem Körper zurückgegeben	Verwenden Sie 204 für erfolgreiche DELETE/PUT/PATCH mit keinem Antworttext	Wenn Sie schnell nach einem Statuscode suchen, während Sie debuggen,

IO Tools hat eine HTTP Status Codes Lookup die den vollständigen Bereich mit Beschreibungen und Hinweisen zur Verwendung jedes Codes abdeckt. Das Muster hinter all diesen Fehlern

Die meisten dieser Fehler entstehen aus demselben Ursprung: Die Behandlung von Statuscodes als lose Kategorien („4xx ist Client-Fehler, 5xx ist Server-Fehler, fertig“) anstatt als ein Protokoll mit spezifischen Semantiken. Die Semantik spielt eine Rolle, weil Clients – Browser, HTTP-Bibliotheken, CDNs, Überwachungstools – tatsächlich auf diese Semantik abgestimmt sind. Ein CDN speichert einen 200 und einen 204 nicht auf die gleiche Weise. Ein HTTP-Client versucht nicht einen 400 und einen 503 mit der gleichen Logik zu wiederholen. Ein Browser speichert einen 302 und einen 301 nicht mit dem gleichen TTL.

Verwenden Sie den richtigen Code. Die Overhead ist null. Der Vorteil bei der Fehlerbehandlung, wenn etwas schiefgeht, ist nicht.

Verwenden Sie den richtigen Code. Die Overhead ist null. Der Debugging-Vorteil, wenn etwas schiefgeht, ist es nicht.

Das könnte Ihnen auch gefallen