HTTP-Statuscodes-Troubleshooting-Leitfaden: Wo Sie nachsehen, wenn Sie 4xx/5xx sehen

Wenn ein API-Aufruf 500 zurückgibt oder ein Alarm auslöst, weil 502er auf einem Endpunkt in die Höhe schnellen, sollte Ihre erste Frage lauten: Auf wessen Problem zeigt dieser Code? Ein HTTP-Statuscode ist im Wesentlichen die Schuldzuweisung des Servers — 4xx heißt, der Client hat etwas falsch gemacht, 5xx heißt, der Server. Diese Ziffer richtig zu lesen bringt Sie auf halbem Weg zur Lösung. Diese Anleitung behandelt die fünf Statuscode-Klassen, geht die häufigsten Codes einzeln mit Ursachen und Debugging-Richtungen durch und klärt die zwei verwirrendsten Paare: 301 vs. 302 und 502 vs. 504.

Die fünf Klassen: Zuerst die Schuld zuweisen

Die erste Ziffer eines Statuscodes bestimmt seine Klasse:

Klasse	Bedeutung	Verantwortlich
1xx	Informativ — Anfrage empfangen, weiter so	Das Protokoll selbst
2xx	Erfolg — die Anfrage wurde bearbeitet	Kein Problem
3xx	Umleitung — der Client muss weitere Schritte tun	Hängt von der Konfiguration ab
4xx	Client-Fehler — die Anfrage selbst ist fehlerhaft	Der Aufrufer
5xx	Server-Fehler — der Server konnte sie nicht verarbeiten	Der Dienst

Die nützlichste Feldregel: Wühlen Sie bei einem 4xx nicht in Server-Logs, und zweifeln Sie bei einem 5xx nicht an Ihren Anfrageparametern. Das ist nur ein Ausgangspunkt — einige Codes (besonders 404 und 502) sind weniger eindeutig, als sie aussehen, wie wir unten sehen werden.

2xx: Auch Erfolg hat Nuancen

200 OK: die generische Erfolgsantwort. Hüten Sie sich vor der „200, aber Geschäftsfehler“-Falle — viele APIs vergraben Anwendungsfehler in einem 200-Body ({"code": 4001, "msg": "insufficient balance"}), sodass Monitoring, das nur Statuscodes beobachtet, echte Fehler übersieht. Geschäftsfehler sollten einen passenden 4xx zurückgeben.

201 Created: eine Ressource wurde erfolgreich erstellt — die klassische Antwort auf ein POST, das eine Bestellung oder einen Nutzer anlegt. Eine wohlerzogene Implementierung legt die URL der neuen Ressource in den Location-Header. Geben Ihre POST-Endpunkte immer 200 zurück, ist der Wechsel zu 201 semantisch korrekter.

204 No Content: Erfolg ohne Antwort-Body, typischerweise für DELETE oder Fire-and-Forget-Übermittlungen. Ein 204 darf keinen Body tragen; manche Frameworks erzwingen trotzdem Inhalt, was strikte HTTP-Clients bricht.

3xx: Weiterleitungen und Caching

301 Moved Permanently: eine permanente Weiterleitung. Suchmaschinen übertragen nahezu alle Ranking-Signale der alten URL (Link-Equity, Indexierung) auf die neue URL, und Browser cachen den Sprung.

302 Found: eine temporäre Weiterleitung. Suchmaschinen behandeln die Original-URL als die kanonische, indexieren sie weiter und übertragen kein Ranking-Gewicht.

Der SEO-Unterschied zwischen beiden verursacht echte Produktionsvorfälle: Eine Seitenmigration, die versehentlich 302 nutzt, sieht ihren Suchverkehr einbrechen, weil das Ranking der alten Domain nie übertragen wird; der umgekehrte Fehler — 301 für eine kurzlebige Kampagne oder einen A/B-Test — bedeutet, dass Browser und CDNs den „permanenten“ Sprung cachen und Nutzer nach Kampagnenende weiter umgeleitet werden. Die Ein-Satz-Regel: permanente Umzüge bekommen 301, temporäre Sprünge 302.

304 Not Modified: kein Fehler — es ist das Zeichen, dass Caching funktioniert. Der Client sendet eine bedingte Anfrage mit If-Modified-Since oder If-None-Match; der Server bestätigt, dass sich nichts geändert hat, und antwortet 304, damit der Client seine lokale Kopie nutzt. Beim Debuggen von „mein Asset aktualisiert sich nicht“ prüfen Sie zuerst, ob die Cache-Header zu aggressiv sind. Umgekehrt: Geben statische Assets jedes Mal 200 statt 304 zurück, ist Ihre Cache-Richtlinie falsch konfiguriert, und Sie verbrennen Bandbreite.

4xx: Das Problem liegt auf der Anfrageseite

400 Bad Request: der Anfrage-Payload selbst ist fehlerhaft — kaputte JSON-Syntax, ein fehlendes Pflichtfeld, ein falscher Parametertyp. Drucken Sie den rohen Request-Body und prüfen Sie ihn Feld für Feld gegen die API-Dokumentation.

401 Unauthorized: nicht authentifiziert. Trotz des Namens heißt es „Ich weiß nicht, wer du bist“ — der Token fehlt, ist abgelaufen oder hat eine schlechte Signatur. Prüfen Sie, ob der Authorization-Header vorhanden ist und ob der Token abgelaufen ist.

403 Forbidden: authentifiziert, aber nicht berechtigt — „Ich weiß, wer du bist, und du bekommst das nicht.“ 401 von 403 zu unterscheiden ist der erste Schritt jeder Berechtigungsuntersuchung: Bei 401 prüfen Sie den Anmeldestatus, bei 403 Rollenkonfiguration, IP-Allowlists oder Ressourceneigentum.

404 Not Found: die Ressource existiert nicht. Achten Sie auf zwei Sonderfälle: ein 404 auf Gateway-Ebene, wo Domain oder Route nicht zugeordnet sind und die Anfrage nie Ihre Anwendung erreicht hat; und absichtliche 404er, die anstelle von 403 genutzt werden, um die Existenz einer Ressource zu verbergen — dann ist „existiert, gibt aber 404 zurück“ tatsächlich ein Berechtigungsproblem.

405 Method Not Allowed: falsche HTTP-Methode, etwa ein GET an einen Endpunkt, der nur POST akzeptiert. Der Allow-Header der Antwort listet die erlaubten Methoden. Das taucht häufig auf, nachdem eine API RESTful wurde, während alter Client-Code sie noch auf die alte Weise aufruft.

429 Too Many Requests: Sie haben ein Rate Limit getroffen. Die Antwort trägt meist einen Retry-After-Header, der sagt, wann Sie es erneut versuchen sollen. Das korrekte Client-Verhalten ist exponentielles Backoff, nicht ein sofortiger Retry — den Endpunkt zu hämmern verlängert das Limit nur. Sind Sie der Diensteigentümer und schnellen die 429er hoch, müssen Ihre Rate Limits oder Quoten überdacht werden.

5xx: Die Serverseite ist gescheitert

500 Internal Server Error: der generische Auffangcode des Servers. Nahezu jede unbehandelte Ausnahme im Anwendungscode erscheint als 500. Der Debugging-Pfad ist eindeutig: Lesen Sie den Stacktrace in den Anwendungslogs. Ein 500 trägt keine weitere Semantik — die Logs sind die Antwort.

502 Bad Gateway: ein Gateway (Nginx, ein Load Balancer, ein API-Gateway) bat einen Upstream-Dienst um eine Antwort und bekam etwas Ungültiges — der Upstream-Prozess ist unten, verweigerte die Verbindung oder gab nicht parsebare Daten zurück. Der Kern: Der Upstream hat nie eine ordentliche Antwort produziert.

503 Service Unavailable: der Dienst kann vorübergehend keine Anfragen bearbeiten. Häufige Ursachen sind absichtliches Last-Abwerfen, Circuit Breaker oder Wartungsmodus, und die Antwort enthält oft Retry-After. Anders als ein 502 ist ein 503 meist absichtlicher Selbstschutz statt eines versehentlichen Ausfalls. Erscheinen 503er, prüfen Sie zuerst, ob Kapazitätsgrenzen oder Circuit-Breaker-Konfiguration ihre Aufgabe tun.

504 Gateway Timeout: Das Gateway wartete auf den Upstream und die Zeit lief ab. Der Upstream lebt, ist aber langsam — langsame Queries, Deadlocks oder eine stockende nachgelagerte Abhängigkeit sind alles Kandidaten. Die Unterscheidung 502 vs. 504 bestimmt direkt Ihren Debugging-Pfad:

• 502: Der Upstream ist tot oder verweigert Verbindungen → prüfen Sie den Upstream-Prozess, seinen Port und seine Health Checks;
• 504: Der Upstream lebt, ist aber zu langsam → prüfen Sie Slow-Query-Logs, Datenbankabfragen und die nachgelagerte Aufrufkette.

Praktische Debugging-Tipps

Bauen Sie eine Gewohnheit auf: Sehen Sie irgendeinen Fehler-Statuscode, bestätigen Sie zuerst, welcher Hop ihn zurückgegeben hat — der Anwendungsserver, das Gateway, das CDN oder etwas, das der Browser fabriziert hat. Führen Sie curl -v aus und lesen Sie die vollständigen Antwort-Header; CDNs und Gateways hinterlassen Fingerabdrücke in Headern wie Server und Via und in eigenen Fehlerseiten. Das erspart Ihnen, Zeit in der falschen Schicht des Stacks zu verbrennen.

Stoßen Sie auf einen unbekannten Code, ist das Nachschlagen in der HTTP-Statusreferenz viel schneller als das Graben durch RFCs: Sie listet jeden Standard-Statuscode, organisiert von 1xx bis 5xx, mit Klartextbeschreibungen, direkt im Browser durchsuchbar. Kombinieren Sie den Debugging-Ansatz dieser Anleitung mit der HTTP-Statusreferenz — der Statuscode sagt Ihnen, welche Seite das Problem besitzt, und der Debugging-Pfad führt Sie zur Grundursache.