HTTP-Statuscodes, die jeder Entwickler kennen sollte

HTTP-Statuscodes sind die Sprache, mit der Server ihren Clients mitteilen, was mit einer Anfrage passiert ist. Jeder Entwickler begegnet ihnen ständig — in den DevTools, in API-Antworten, in Fehler-Logs, in Slack-Alerts um 3 Uhr morgens. Zu wissen, was ein Code tatsächlich bedeutet, wann man welchen Code in eigenen APIs verwendet und was häufige Codes über einen Fehler aussagen, macht Sie beim Debuggen deutlich schneller und hilft beim Aufbau besserer Dienste.

Jeden HTTP-Statuscode können Sie mit der BrowseryTools HTTP-Statuscode-Referenz nachschlagen — kostenlos, ohne Anmeldung, alles läuft in Ihrem Browser.

Die fünf Kategorien

Statuscodes sind dreistellige Zahlen. Die erste Ziffer definiert die Kategorie:

• 1xx — Informational: Die Anfrage wurde empfangen; die Verarbeitung läuft. Diese Codes sind in den meisten Anwendungen selten.
• 2xx — Erfolg: Die Anfrage wurde empfangen, verstanden und akzeptiert.
• 3xx — Weiterleitung: Zum Abschluss der Anfrage ist eine weitere Aktion erforderlich. Der Client sollte einer Weiterleitung folgen.
• 4xx — Client-Fehler: Die Anfrage war fehlerhaft oder nicht autorisiert. Der Client hat einen Fehler gemacht.
• 5xx — Server-Fehler: Der Server konnte eine gültige Anfrage nicht erfüllen. Der Server hat einen Fehler gemacht.

Diese Erstziffer-Regel ist wichtig: Wenn Sie einen Statuscode nicht kennen (z. B. 429 oder 451), wissen Sie zumindest, ob das Problem auf der Client- oder Serverseite liegt und ob die Anfrage letztendlich erfolgreich war.

2xx: Erfolgscodes

Diese Codes teilen dem Client mit, dass die Anfrage funktioniert hat. Der spezifische Code kommuniziert, wie sie funktioniert hat:

• 200 OK — der universelle Erfolg. Der Response-Body enthält die angeforderten Daten. Wird für GET-Anfragen und die meisten Antworten verwendet, die Inhalte zurückgeben.
• 201 Created — eine neue Ressource wurde erstellt. Sollte einen Location-Header enthalten, der auf die URL der neuen Ressource zeigt. Verwenden Sie diesen Code für POST-Anfragen, die Datensätze erstellen, nicht 200.
• 204 No Content — die Anfrage war erfolgreich, aber es gibt keinen Response-Body. Üblich für DELETE-Anfragen und PATCH/PUT-Operationen, bei denen der Client keine aktualisierten Daten zurückbenötigt. Die Antwort darf keinen Body enthalten.
• 206 Partial Content — wird bei Range-Anfragen verwendet (dem Range-Header). Videoplayer verwenden dies, um bestimmte Byte-Bereiche einer Mediendatei anzufordern, ohne die gesamte Datei herunterzuladen.

# REST API design pattern
POST   /api/users        → 201 Created  (body: new user object, Location: /api/users/123)
GET    /api/users/123    → 200 OK       (body: user object)
PATCH  /api/users/123    → 200 OK       (body: updated user) or 204 No Content
DELETE /api/users/123    → 204 No Content

3xx: Weiterleitungscodes

Weiterleitungen teilen dem Client mit, woanders nachzusehen. Der Location-Header enthält die neue URL. Der wichtigste Unterschied liegt zwischen dauerhaften und temporären Weiterleitungen sowie zwischen Weiterleitungen, die die HTTP-Methode beibehalten, und solchen, die sie ändern.

• 301 Moved Permanently — die Ressource hat eine neue dauerhafte URL. Browser und Suchmaschinen speichern dies im Cache. Der Browser verwendet GET für die Weiterleitung, unabhängig von der ursprünglichen Methode (eine historische Eigenheit). Verwenden Sie diesen Code, wenn Sie eine URL dauerhaft umbenennen oder HTTP zu HTTPS umleiten.
• 302 Found — temporäre Weiterleitung. Wie 301 ändert der Browser POST bei der Weiterleitung in GET (gemäß Spezifikation, auch wenn die Spezifikation hier „falsch" war — siehe 307). Verwenden Sie 302 nur, wenn die Weiterleitung wirklich temporär ist.
• 304 Not Modified — die zwischengespeicherte Version ist noch aktuell; kein Body. Der Server sendet dies als Antwort auf einen bedingten GET-Request (mit If-None-Match oder If-Modified-Since). Der Browser verwendet seine zwischengespeicherte Kopie. Wichtig für CDN-Effizienz und Bandbreitenreduzierung.
• 307 Temporary Redirect — wie 302, aber die Spezifikation garantiert, dass die ursprüngliche HTTP-Methode beibehalten wird. Wenn ein POST zu einem 307 führt, sendet der Browser einen POST an die neue URL. Verwenden Sie 307 statt 302 für temporäre Nicht-GET-Weiterleitungen.
• 308 Permanent Redirect — wie 301, garantiert aber auch die Methodenbeibehaltung. Der moderne Standard für dauerhafte Weiterleitungen.

Häufiges Missverständnis: 301 vs. 302 für SEO

Suchmaschinen behandeln 301 als Signal, „Link-Equity" (PageRank) von der alten URL auf die neue zu übertragen und ihren Index zu aktualisieren. Ein 302 signalisiert dem Crawler, dass die Weiterleitung temporär ist, sodass er die ursprüngliche URL weiterhin indexiert. 302 statt 301 zu verwenden, wenn Sie eine dauerhafte Weiterleitung meinen, kann den SEO-Vorteil von Weiterleitungen zunichte machen. Umgekehrt veranlasst das Verwenden von 301 bei einer temporären Weiterleitung Suchmaschinen, diese zu cachen, was die Rückgängigmachung erschwert.

4xx: Client-Fehlercodes

Diese Codes zeigen an, dass der Client eine fehlerhafte Anfrage gesendet hat. Geben Sie keine 5xx-Codes für Client-Fehler zurück — das macht das Monitoring irreführend und erschwert die Unterscheidung, ob ein Problem ein Serverfehler oder eine fehlerhafte Client-Eingabe ist.

• 400 Bad Request — die Anfrage ist fehlerhaft. Fehlende Pflichtfelder, ungültiges JSON, falsche Datentypen. Der allgemeinste 4xx; verwenden Sie spezifischere Codes, wenn verfügbar.
• 401 Unauthorized — trotz des Namens bedeutet dies „nicht authentifiziert". Der Client hat keine Anmeldedaten angegeben, oder die Anmeldedaten waren ungültig. Die Antwort sollte einen WWW-Authenticate-Header enthalten, der angibt, wie man sich authentifiziert. Der Name ist ein historischer Fehler — „nicht authentifiziert" wäre treffender.
• 403 Forbidden — authentifiziert, aber nicht autorisiert. Der Server weiß, wer Sie sind (oder es ist irrelevant), und Sie haben keine Berechtigung. Anders als bei 401 hilft eine erneute Authentifizierung nicht. Verwenden Sie 403, wenn ein Benutzer versucht, auf eine Ressource zuzugreifen, für die er keine Berechtigung hat.
• 404 Not Found — die Ressource existiert unter dieser URL nicht. Wird auch zurückgegeben, wenn ein Server die Existenz einer Ressource vor nicht autorisierten Benutzern verbergen möchte (403 würde bestätigen, dass die Ressource existiert; 404 verbirgt diese Tatsache).
• 409 Conflict — die Anfrage steht im Widerspruch zum aktuellen Zustand der Ressource. Klassisches Beispiel: Versuch, einen Benutzer mit einer bereits vorhandenen E-Mail-Adresse zu erstellen, oder eine Ressource mit einer veralteten Version zu aktualisieren (Optimistic-Locking-Konflikt).
• 422 Unprocessable Entity — die Anfrage ist syntaktisch korrekt (gültiges JSON, richtiger Content-Type), aber semantisch ungültig (ein Pflichtfeld ist vorhanden, enthält aber einen ungültigen Wert oder verstößt gegen eine Geschäftsregel). Rails hat die Verwendung von 422 für Validierungsfehler populär gemacht. Spezifischer als 400.
• 429 Too Many Requests — Rate-Limit überschritten. Sollte einen Retry-After-Header enthalten, der dem Client mitteilt, wie lange er warten soll. Unverzichtbar für jede öffentliche API.

401 vs. 403: Der entscheidende Unterschied

Dies ist eines der am häufigsten verwechselten Paare:

GET /api/admin/users
Authorization: (none)
→ 401 Unauthorized
   "You haven't told me who you are. Log in first."

GET /api/admin/users
Authorization: Bearer <valid-regular-user-token>
→ 403 Forbidden
   "I know who you are. You're not an admin. Access denied."

5xx: Server-Fehlercodes

• 500 Internal Server Error — ein allgemeiner Auffang-Code für unerwartete serverseitige Fehler. Eine unbehandelte Ausnahme, eine Null-Referenz, eine Datenbankabfrage, die einen Fehler geworfen hat. Geben Sie dem Client keine Stack-Traces preis; protokollieren Sie sie serverseitig.
• 502 Bad Gateway — der als Proxy oder Gateway fungierende Server hat eine ungültige Antwort von einem vorgelagerten Server erhalten. Häufig wenn Ihr Load-Balancer oder Reverse-Proxy die dahinterliegenden Anwendungsserver nicht erreichen kann — die App ist abgestürzt oder hört nicht auf dem richtigen Port.
• 503 Service Unavailable — der Server kann vorübergehend keine Anfragen bearbeiten. Möglicherweise überlastet, mitten in einem Deployment oder in der Wartung. Sollte einen Retry-After-Header enthalten, wenn die Ausfalldauer bekannt ist.
• 504 Gateway Timeout — der Proxy oder Gateway hat keine rechtzeitige Antwort vom vorgelagerten Server erhalten. Der vorgelagerte Server ist erreichbar und antwortet, aber zu langsam. Häufiges Symptom bei Datenbankabfragen, die zu lange dauern, oder externen API-Aufrufen, die hängen bleiben.

Statuscodes im REST-API-Design

Die richtigen Statuscodes machen Ihre API selbstdokumentierend und leichter integrierbar. Einige Richtlinien:

• Geben Sie niemals 200 mit einem Fehlerobjekt im Body zurück. Wenn eine Anfrage fehlgeschlagen ist, sollte der Statuscode das widerspiegeln. Clients sollten allein anhand des Statuscodes erkennen können, ob sie einen Fehler behandeln müssen.
• Verwenden Sie 201 und einen Location-Header beim Erstellen von Ressourcen via POST. Damit können Clients die URL der neuen Ressource entdecken, ohne den Body zu parsen.
• Geben Sie 422 (nicht 400) für Validierungsfehler zurück und fügen Sie einen strukturierten Fehler-Body hinzu, der angibt, welche Felder fehlgeschlagen sind und warum.
• Verwenden Sie 409 für Konflikte, die eine Auflösung auf Anwendungsebene erfordern, nicht nur für fehlerhafte Eingaben.
• Implementieren Sie 429 mit Rate-Limiting von Anfang an bei jedem öffentlichen Endpunkt — es ist viel schwieriger, es nachträglich hinzuzufügen.

Statuscodes in den DevTools debuggen

Öffnen Sie die Registerkarte „Netzwerk" in den Browser-DevTools und suchen Sie nach roten Anfragen — das sind 4xx- oder 5xx-Antworten. Klicken Sie auf eine Anfrage, um den genauen Statuscode, die Antwort-Header (nützlich für WWW-Authenticate, Location, Retry-After) und den Antwort-Body zu sehen (der oft eine Fehlermeldung vom Server enthält). Aktivieren Sie bei Weiterleitungen „Log aufbewahren", damit das DevTools-Panel beim Seitennavigieren nicht geleert wird — sonst verpassen Sie die Weiterleitungskette.

Wenn Sie einem unbekannten Statuscode begegnen, gibt Ihnen die BrowseryTools HTTP-Statuscode-Referenz die offizielle Beschreibung, den zugehörigen RFC und Hinweise zur gängigen Verwendung — ohne Ihren Browser-Tab verlassen zu müssen.