HTTP-Statuscodes sind die dreistelligen Zahlen, die ein Server am Anfang jeder Antwort zurückgibt, um zusammenzufassen, was passiert ist. Anhand dieser Codes entscheiden Browser, Clients, Proxies und CDNs, ob sie cachen, weiterleiten, erneut versuchen oder einen Fehler an den Nutzer durchreichen.
Jeder Statuscode gehört - abhängig von der ersten Ziffer - zu einer von fünf Klassen: 1xx informativ, 2xx Erfolg, 3xx Weiterleitung, 4xx Client-Fehler, 5xx Server-Fehler. Sobald du die Klasse kennst, weißt du meistens schon grob, was los ist, auch ohne den konkreten Code nachzuschlagen.
Die meisten Anwendungen kommen mit einem überschaubaren Kern aus (200, 201, 204, 301, 302, 304, 400, 401, 403, 404, 409, 422, 429, 500, 502, 503). Zu wissen, was jeder davon *wirklich* bedeutet - und worin der Unterschied zwischen 401 Unauthorized und 403 Forbidden oder 301 Moved Permanently und 302 Found liegt - macht dich zu einem souveräneren Backend- bzw. API-Entwickler.
Was du beim Stöbern in dieser Referenz lernst
Die erste Ziffer verrät immer die Klasse: 1xx Info, 2xx Erfolg, 3xx Redirect, 4xx Client-Fehler, 5xx Server-Fehler.
Statuscodes sind *Teil des Vertrags*, den eine API anbietet - Clients sollten sich am Code orientieren, nicht Fehlermeldungen aus dem Body parsen.
4xx heißt: Der Client hat etwas falsch gemacht (ungültige Eingabe, fehlende Auth, fehlende Ressource). 5xx heißt: Der Server ist gescheitert, egal was der Client gemacht hat.
So nutzt du die Statuscode-Referenz Schritt für Schritt
1
Nach Code oder Name suchen
Tippe eine Zahl (404, 429) oder ein Stichwort (auth, redirect, rate limit) - die passenden Codes werden live gefiltert.
2
Nach Klasse filtern
Mit den Klassen-Chips (1xx, 2xx, 3xx, 4xx, 5xx) grenzt du die Liste ein, wenn du eher stöbern als gezielt suchen willst.
3
Die verständliche Erklärung lesen
Jeder Eintrag erklärt, wann der Code geschickt wird, wie sich Clients typischerweise verhalten und was die häufigste Ursache ist.
4
Verwandte Codes vergleichen
Über die Querverweise zwischen oft verwechselten Paaren (401 vs 403, 301 vs 302) findest du den richtigen Code für deine API.
Erfolg, aber ohne Body. Üblich nach DELETE- oder PUT-Aufrufen, bei denen es nichts zurückzugeben gibt.
Alle drei sind Erfolgs-Codes - der Unterschied liegt darin, was die Antwort transportiert. 201 sollte einen Location-Header enthalten, der auf die neue Ressource zeigt; 204 ist per Definition leer.
Temporäre Weiterleitung. Browser fragen die ursprüngliche URL bei jedem Request neu ab; Bookmarks bleiben auf der alten URL.
Nimm 301, wenn du eine Ressource tatsächlich umgezogen hast (Rebranding, URL-Umstrukturierung). Nimm 302 für kurzlebige Weiterleitungen wie A/B-Tests, Login-Redirects oder Wartungsseiten.
Der Server weiß, wer du bist, aber du hast keine Berechtigung für diese Ressource.
Wenn andere Credentials das Problem lösen könnten, gib 401 zurück. Wenn keine Credentials etwas ändern würden (die Ressource ist für diesen User schlicht tabu), gib 403 zurück.
Gateway Timeout - ein Proxy hat den Upstream zwar erreicht, aber keine rechtzeitige Antwort bekommen.
Alle vier sind Server-Fehler, erzählen beim Debuggen aber sehr unterschiedliche Geschichten. 500 zeigt auf deine App; 502 und 504 zeigen auf den Netzwerkpfad; 503 zeigt auf die Kapazität.
Häufige Fehler bei HTTP-Statuscodes
200 OK mit {"error": "..."} im Body zurückgeben. Der Statuscode ist Teil des Vertrags - nimm den richtigen (400, 404, 500), damit Clients sich darauf verlassen können.
401 für Berechtigungsfehler verwenden. 401 ist für die Authentifizierung; verweigerte Berechtigungen sind 403.
200 für neu angelegte Ressourcen statt 201 mit Location-Header.
FAQ zu HTTP-Statuscodes
Was bedeutet HTTP 404?
404 Not Found heißt: Der Server hat die Anfrage verstanden, aber unter dieser URL gibt es keine Ressource. Meist ist der Pfad falsch, die Ressource wurde gelöscht oder die URL ist vertippt.
Was ist der Unterschied zwischen 401 und 403?
401 Unauthorized heißt: Du bist nicht authentifiziert - der Server weiß nicht, wer du bist. 403 Forbidden heißt: Du bist zwar authentifiziert, hast aber keine Berechtigung für die Ressource. Andere Credentials können 401 lösen; bei 403 helfen sie nicht.
Was ist der Unterschied zwischen 301 und 302?
301 Moved Permanently ist eine dauerhafte Weiterleitung - Browser und Suchmaschinen aktualisieren ihre Einträge. 302 Found ist eine temporäre Weiterleitung - Clients rufen weiterhin die ursprüngliche URL auf. Nimm 301 für endgültige Umzüge, 302 für vorübergehende Umwege.
Was bedeutet HTTP 500?
500 Internal Server Error ist ein allgemeiner serverseitiger Fehler, der meist geworfen wird, wenn eine Exception nach oben durchschlägt, ohne abgefangen zu werden. Der Client hat nichts falsch gemacht - dein Server hat eine gültige Anfrage nicht verarbeitet.
Sollte ich immer einen spezifischen Statuscode verwenden?
Ja. Generisches 200 OK für Fehler oder 500 für alles, was schiefläuft, macht APIs unbrauchbar. Wähle den spezifischsten passenden Code - Clients, Proxies, Monitoring und Retry-Logik richten sich alle nach dem Statuscode.
Was bedeutet HTTP 429?
429 Too Many Requests wird gesendet, wenn ein Client ein Rate-Limit erreicht hat. Die Antwort sollte einen Retry-After-Header enthalten, der dem Client sagt, wann er es wieder versuchen darf.
