HTTP-Statuscodes Wann 404 statt 410 statt 301 zurückgeben und spekulieren aufhören

Sie haben 200 mit {"error": "user not found"} im Körper zurückgegeben. Ihre 301-Statuscodes sind tatsächlich 302-Statuscodes. Gelöschte Ressourcen geben immer noch 404 zurück. Lassen Sie uns die Statuscodes durchgehen, die Entwickler am häufigsten falsch verwenden, und was stattdessen zurückgegeben werden sollte.

4xx vs 5xx: Nicht dasselbe Fass

Der grundlegende Unterschied in HTTP-Statuscodes: 4xx ist die Schuld des Clients, 5xx ist Ihre. In der Theorie einfach, in der Praxis jedoch ständig verletzt.

Der häufigste Verstoß: Rückgabe von 500 bei einem Validierungsfehler. Ein Benutzer hat falsch formatierten JSON an Ihre API gesendet. Das ist ein 400 Bad Request — das Payload war falsch. Ein 500 sagt dem Client „wir sind abgestürzt“, was Alarme auslöst, als Serverfehler protokolliert wird und automatische Systeme erneut versuchen (was Ihren schlechten Tag noch schlimmer macht). Wenn der Client falsche Daten gesendet hat, sagen Sie dies mit einem 4xx.

404 vs 410: Das Problem der gelöschten Ressource

404 Not Found bedeutet: „Ich habe es gerade nicht, aber versuchen Sie es später.“ Spaziergänger — auch Googlebot eingeschlossen — behandeln 404 als temporär. Sie werden es unendlich oft erneut prüfen.

410 Gone bedeutet: „Diese Ressource wurde dauerhaft gelöscht. Fragen Sie aufhören.“ Googlebot entfernt 410-URLs aus dem Index schneller als 404-URLs und beendet die Crawling-Phase früher. Dies ist wichtig für SEO und für das Crawlbudget auf großen Websites.

Die praktische Regel: Wenn Ihre API eine Ressource hart löscht und sie nie wieder zurückkommt, geben Sie auf weiteren Anfragen 410 zurück. Der einzige Grund, warum 404 für eine gelöschte Ressource bevorzugt wird, ist, wenn sie wiederhergestellt werden könnte — mit einer weichen Löschung und einem Wiederherstellungszeitfenster, einem veröffentlichten Beitrag, der erneut veröffentlicht werden könnte, und so weiter. Andernfalls ist 410 ehrlicher und Suchmaschinen werden Ihnen dafür dankbar sein.

301 vs 302 (und warum 307/308 existieren)

301 Moved Permanently: Diese URL ist dauerhaft verschwunden, verwenden Sie die neue. Browser speichern 301s aggressiv. Suchmaschinen übertragen Link-Equity an das Ziel. Wenn Sie Domänen zusammenführen oder eine Website dauerhaft verschieben, ist 301 das, was Sie wünschen.

302 Found: Gehe zu dieser anderen URL für jetzt, aber kehre später an die ursprüngliche zurück. Kein Caching. Keine Übertragung von Link-Equity. Verwenden Sie es für Login-Redirects, temporäre Wartungsseiten oder A/B-Tests.

Der Fehlermodus: Verwendung von 302 für dauerhafte Umstellungen. Sie denken „das gleiche, nur anders“, aber Suchmaschinen übertragen keine Link-Equity über 302. Jahre lang gearbeitete SEO-Resultate bleiben an der alten URL hängen, während die neue URL nichts rankt. Wenn Sie etwas dauerhaft verschieben, verwenden Sie 301.

Dann gibt es 307 Temporary Redirect und 308 Permanent Redirect. Diese sind methodensichere Varianten: Wenn ein Browser bei der Verfolgung einer 301/302 einen POST auf GET herunterstufen könnte, behalten 307/308 die ursprüngliche HTTP-Methode bei. Wenn Sie API-Endpunkte mit POST-Body verschieben, behält 307 (temporär) oder 308 (dauerhaft) die Methode bei.

Code	Typ	Caches?	Behält die Methode bei?	Verwenden Sie für
301	Dauerhaft	Ja	Nein (kann auf GET heruntergestuft werden)	Dauerhafte Websiteumstellung, URL-Konsolidierung
302	Temporär	NEIN	Nein (kann auf GET heruntergestuft werden)	Login-Redirects, temporäre Unverfügbarkeit
307	Temporär	NEIN	Ja	Temporäre Redirect für API-POST-Endpunkte
308	Dauerhaft	Ja	Ja	Dauerhafte Redirect für API-POST-Endpunkte

401 vs 403: Authentifizierung vs Autorisierung

Der Name ist verwirrend. 401 Unauthorized bedeutet tatsächlich nicht authentifiziert — Sie sind nicht angemeldet oder Ihre Anmeldeinformationen fehlen oder sind ungültig. 403 Forbidden bedeutet, dass Sie authentifiziert sind, aber keine Berechtigung haben, auf diese Ressource zuzugreifen.

Der praktische Unterschied: Ein 401 sollte eine Anmeldeseite oder eine Token-Neuvergabe anfordern. Ein 403 sollte eine „Zugriff verweigert“-Meldung anzeigen. Wenn Sie das falsche zurückgeben, weiß der Client nicht, ob er Anmeldeinformationen anfordern oder aufgeben soll.

Es gibt auch eine Sicherheitsdimension. Einige APIs geben 404 statt 403 für Ressourcen zurück, die vom Aufrufenden nicht zugänglich sind, um zu verhindern, dass bekannt wird, dass die Ressource existiert. Wenn Sie 403 auf eine Ressource aus einem anderen Tenant zurückgeben, haben Sie bestätigt, dass sie existiert. Ein 404 ist sicherer, obwohl es den Debug-Prozess für legitime Benutzer erschwert. Wählen Sie die entsprechende Balance für Ihr Sicherheitsmodell und wenden Sie es konsistent an.

429: Begrenzung der Anzahl der Anfragen, mit dem Header, der tatsächlich hilft

Ein bloßer 429 Too Many Requests ist ärgerlich. Ein 429 mit einem Retry-After Header ist tatsächlich nützlich.

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

Retry-After kann eine Zahl von Sekunden oder ein HTTP-Datum sein. Gut verhaltenen Clients werden automatisch zurückgehen. Ohne diesen Header geben Sie einen Fehlercode zurück und hoffen, dass der Client herausfindet, wann er erneut versuchen soll — die meisten werden einfach sofort erneut an Ihren Endpunkt schlagen, was das Ziel der Begrenzung der Anfragen verletzt.

Geben Sie 503 nicht für Begrenzungen der Anzahl der Anfragen zurück. 503 bedeutet „Dienst nicht verfügbar“ — Infrastruktur ausfallen, Deployment in Bearbeitung, Schaltkreis offen. Begrenzung der Anzahl der Anfragen ist eine Richtlinie, nicht ein Dienstfehler. 429 existiert genau dafür.

Das „200 mit einem Fehlerkörper“-Muster

Dieses Muster taucht immer wieder in Produktions-APIs auf und muss aufhören:

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "error", "message": "user not found"}

Dies bricht alles, was auf HTTP-Semantik basiert. Überwachungstools berichten über den Erfolg des Anrufs. Lastbalancer leitet ihn weiter. Clientbibliotheken werfen keine Fehler. Die Protokolle sehen sauber aus, während Benutzer Fehler sehen. Die Lösung ist eine einzige Zeile: geben Sie den richtigen Statuscode zurück. 200 bedeutet, dass es funktioniert. Wenn es nicht funktioniert, geben Sie kein 200 zurück.

Die gleiche Logik gilt für 201 vs 200 bei der Erstellung von Ressourcen. Wenn eine POST-Anfrage an /users eine neue Benutzer erstellt, geben Sie 201 Created mit einem Location Header zurück, der auf die neue Ressource zeigt. Wenn Sie 200 zurückgeben, haben Sie Informationen verloren, die Ihre Clients nutzen könnten, um eine zusätzliche Runde zu vermeiden.

API-Szenario → Richtiges Statuscode

Hier ist eine Referenztabelle für die Szenarien, die am häufigsten in REST-API-Entwicklung auftreten:

Szenario	Statuscode	Hinweise
Anfragekörper ist falsch formatierter JSON	400 Bad Request	Fügen Sie eine Nachricht hinzu, die auf den Parse-Fehler zeigt
Fehlende oder ungültige Felder in der Anfrage	422 Unprocessable Entity	422 ist präziser als 400 für semantische Validierungsfehler
Authentifizierungs-Token fehlt oder ist abgelaufen	401 Unauthorized	Einschließen WWW-Authenticate Header
Authentifiziert, aber keine Berechtigung	403 Forbidden	Oder 404, wenn die Versteckung der Ressourcenexistenz eine Anforderung ist
Ressource nicht gefunden, könnte	404 Not Found	für temporäre Abwesenheit oder unbekannte Ressourcen
Ressource dauerhaft gelöscht	410 Gone	Spaziergänger werden früher aufhören, sie zu prüfen
Eine neue Ressource erstellt	201 Created	Hinzufügen Location: /resources/new-id Header
DELETE erfolgreich, kein Körper	204 No Content	Geben Sie kein leeres JSON-Objekt mit 200 zurück
Dauerhafte URL-Änderung	301 Moved Permanently	Suchmaschinen übertragen Link-Equity
POST wird beim Folgen auf GET herabgestuft	302 Found	Kein Caching, keine Übertragung von Link-Equity
Übersteigt die Rate-Limit	429 Too Many Requests	Fügen Sie immer Retry-After
Unvorhersehbarer Serverfehler	500 Internal Server Error	Leak keine Stapelverfolgungen im Körper
Übergeordnete Abhängigkeit ist ausfallen	503 Service Unavailable	Hinzufügen Retry-After wenn die Ausfallzeit begrenzt ist
POST-Redirect, Methode beibehalten	307 oder 308	307 temporär, 308 dauerhaft

Wenn Sie in der Mitte eines PR-Verfahrens sind und wissen müssen, was ein Statuscode tatsächlich bedeutet, bietet das HTTP-Status-Codes-Referenzwerkzeug die Spezifikation, typische Anwendungsfälle und die RFC, die es definiert.

Prüfung Ihrer Redirect-Ketten

Nach einer Website-Übertragung oder URL-Neuorganisation lohnt es sich, die vollständige Redirect-Kette zu überprüfen — besonders wenn Sie 301s später aktualisiert haben, um auf eine andere URL zu zeigen, was mehrstufige Ketten erzeugt, die Link-Equity verlieren. Das Richtlinienprüfer verfolgt die Kette und zeigt jedes Statuscode in Reihenfolge, damit Sie sicherstellen können, dass alles in einem Schritt gelöst wird.

Das könnte Ihnen auch gefallen