HTTP-Statuscodes: Was 1xx bis 5xx bedeuten und was bei typischen Fehlern zu tun ist

HTTP-Statuscodes im Betrieb einordnen: Semantik, Cache- und Retry-Verhalten, Logs und typische Fehlinterpretationen

HTTP-Statuscodes sind im Betrieb weniger „Fehlermeldungen“ als verdichtete Signale über den Zustand einer Anfrage entlang einer Kette aus Client, Proxy/CDN, Load-Balancer und Origin. Die gleiche Zahl kann je nach Methode, Antwortheadern und Kontext (Browser-Navigation, API-Call, Background-Job) unterschiedliche Folgen haben. Eine belastbare Einordnung trennt deshalb Semantik (was bedeutet der Code), Transportrealität (wer hat ihn erzeugt) und Steuerwirkung (Cache, Retry, User-Agent-Verhalten).

Semantik im Zusammenspiel mit Methode, Headern und Body

Statuscodes beschreiben die Verarbeitung einer konkreten Request-Response-Interaktion. Bei identischem Code können sich die Erwartungen an Body und Folgeaktionen unterscheiden: HEAD liefert nie einen Message-Body, 204 enthält keinen, 304 darf keinen enthalten und setzt auf Validatoren wie ETag oder Last-Modified. Bei Redirects entscheidet nicht nur der Code, sondern auch die Kombination aus Location, Method-Rewrite-Regeln (z. B. bei 303) und Caching-Headern.

In REST-APIs ist die Präzision der Semantik entscheidend, weil Clients automatisieren. Ein 400 signalisiert syntaktische oder semantische Probleme der Anfrage, während 422 typischerweise Validierungsfehler auf Feldebene transportiert. 401 bedeutet fehlende oder ungültige Authentisierung und verlangt in der Regel WWW-Authenticate; 403 steht für verweigerte Autorisierung trotz identifizierbarer Identität. Für idempotente Methoden wie GET, PUT oder DELETE sind Retry-Strategien technisch eher vertretbar als für nicht-idempotente POST, sofern kein Idempotency-Key eingesetzt wird.

Cache-Wirkung und Revalidierung: wann Codes „sticky“ werden

Ob eine Antwort im Cache landet, hängt nicht primär am Statuscode, sondern an Cache-Headern und Cache-Implementierung. Trotzdem existieren betriebliche Muster: 200 wird häufig gecacht, 301 kann in Browsern und Zwischen-Caches sehr langlebig werden, 302/307 eher temporär. 304 ist keine „Fehlerantwort“, sondern das Ergebnis einer bedingten Anfrage mit If-None-Match oder If-Modified-Since; sie reduziert Bandbreite, setzt aber korrekte Validatoren voraus. Fehlkonfigurationen führen zu irritierenden Effekten: ein zu aggressives Cache-Control: public, max-age=... auf dynamischen Fehlerseiten kann 404– oder 500-Antworten im CDN „einfrieren“.

Retry-Verhalten: wann Wiederholungen helfen und wann sie Schaden anrichten

Retries sind primär eine Funktion von Client-Logik, SDKs, Proxies und Load-Balancern; der Statuscode liefert nur Hinweise. 429 und 503 sind für kontrollierte Wiederholungen geeignet, idealerweise mit Retry-After sowie Exponential Backoff und Jitter. 502/504 können transiente Upstream-Probleme anzeigen; bei dauerhaft falscher Upstream-Konfiguration verstärken Retries jedoch die Last. 500 ist semantisch „serverseitig“, aber operativ heterogen: vom Nullpointer bis zu Timeouts in Downstream-Abhängigkeiten. Ohne Korrelation über Request-IDs werden Retries schnell zum Rauschen.

• Retry-freundliche Signale: 429 und 503 bevorzugen, wenn Drosselung oder geplante Degradation kommuniziert werden soll; Retry-After setzen und Grenzen für parallel laufende Versuche definieren.
• Idempotenz absichern: Bei nicht-idempotentem POST Wiederholungen nur mit Idempotency-Key, z. B. Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000, oder serverseitiger Deduplizierung zulassen.
• Timeout-Kaskaden entschärfen: Bei 504 und 499 (Nginx, clientseitiger Abbruch) Timeouts entlang der Kette konsistent staffeln; typische Prüfpunkte sind proxy_read_timeout, gunicorn --timeout oder Load-Balancer-Idle-Timeouts.
• Retry-Schäden vermeiden: Bei systematischen 401/403/404 keine automatischen Retries; stattdessen Konfiguration, Routing, Credentials oder Deployment-Artefakte prüfen.

Logs, Metriken und Korrelation: wer hat den Code wirklich erzeugt?

Im Betrieb zählt die Quelle des Statuscodes. Ein Browser sieht nur den Endcode, während im Backend mehrere Hops beteiligt sein können. Reverse Proxies und CDNs erzeugen eigene Codes (z. B. bei Origin-Timeouts) oder maskieren Upstream-Fehler. Zudem existieren nicht standardisierte, aber verbreitete Codes in Logs, etwa 499 (Client schließt Verbindung) oder 520-Klassen bei bestimmten CDNs. Für eine saubere Analyse werden daher mindestens Request-Method, Pfad, Host, Response-Code, Upstream-Status, Latenzen und eine durchgängige Correlation-ID benötigt.

Praktisch bewährt sich die parallele Betrachtung von Access-Log, Upstream-Log und Applikations-Log. Bei Nginx liefern Felder wie $status, $upstream_status, $request_time und $upstream_response_time schnell Hinweise, ob die Antwort am Edge, im Proxy oder in der Anwendung entstand. In Microservice-Setups sollte eine Trace-ID (z. B. traceparent) vom Edge bis zum letzten Downstream propagiert werden, sonst bleiben 502/504 ohne Ursachenbezug. Für APIs sind zusätzlich Rate-Limit-Header und Auth-Fehlerdetails (ohne sensitive Daten) wichtig, um 401/403/429 differenzieren zu können.

Typische Fehlinterpretationen, die Incident-Triage verzögern

• 304 als „kaputte Seite“: 304 ist in der Regel ein gutes Zeichen; Probleme liegen häufiger bei inkonsistenten Validatoren (ETag-Wechsel durch Kompression/Varianten) oder fehlerhaftem Vary.
• 403 als „Login kaputt“: 403 bedeutet nicht Authentisierung, sondern fehlende Berechtigung oder Policy-Block; bei WAF/CSRF/Geo-Blocking entstehen 403 oft außerhalb der Anwendung.
• 404 mit erfolgreichem HTML als „harmlos“: „Soft-404“ (inhaltlich Fehlerseite, technisch 200) verfälscht Monitoring und SEO-Integrität; umgekehrt kann ein echtes 404 durch Negativ-Caching länger sichtbar bleiben als die Ursache.
• 502 gleich „Server down“: 502 bedeutet „Bad Gateway“ und zeigt oft Protokoll-/TLS-/Header-Probleme zwischen Proxy und Upstream, fehlerhafte Health-Checks oder abgestürzte Worker, nicht zwingend einen kompletten Ausfall.
• 500 als Enddiagnose: 500 ist ein Sammelstatus; ohne konkrete Fehlerklasse im Application-Log, passende Alarmierung nach Endpoint und Korrelation über X-Request-ID bleibt die Maßnahme unscharf.

Referenztabellen 1xx–5xx: Kurzbeschreibung, technische Bedeutung, typische Ursachen (Client/Server/Proxy/CDN) und empfohlene Maßnahmen

Die folgenden Referenztabellen ordnen gängige HTTP-Statuscodes nach Klassen ein und ergänzen die Kurzbeschreibung um technische Bedeutung, typische Auslöser entlang der Kette Client–Origin–Proxy/CDN sowie konkrete Maßnahmen. In Proxy- und CDN-Setups entstehen Fehler häufig nicht am Origin, sondern durch Timeouts, Policy-Entscheidungen oder Edge-Caching. Bei REST-APIs beeinflussen Content-Negotiation, Authentifizierung und Semantik der Methode (GET, POST, PUT, DELETE) die korrekte Codewahl.

1xx (Informational) und 2xx (Successful): Protokollfluss und Erfolg

3xx (Redirection): Weiterleitungen, Caching und Edge-Rewrites

4xx (Client Error): Anfrage ungültig, nicht autorisiert oder durch Policies geblockt

5xx (Server Error): Origin-Fehler, Upstream-Probleme und Edge-Timeouts

Schnelle Diagnostik: Einordnung nach Quelle (Browser, Origin, Proxy/CDN)

Bei identischen Statuscodes unterscheiden sich Ursachen je nach Erzeuger. Ein 403 aus dem Origin folgt meist aus Autorisierung oder Dateirechten; ein 403 vom CDN resultiert häufig aus WAF-, Geo- oder Bot-Policies. Timeouts zeigen sich am Edge oft als 504, obwohl der Origin später noch verarbeitet. Hinweise liefern Response-Header wie Via, Server oder CDN-spezifische Trace-IDs sowie abweichende Error-Seiten.

• Quelle identifizieren: Response-Header auf Proxy-/CDN-Spuren prüfen, z. B. Via, X-Request-ID, CDN-Trace-IDs; bei Bedarf Vergleich ohne Edge über direkten Origin-Host (nur kontrolliert, z. B. intern) oder per expliziter Auflösung mit curl --resolve example.com:443:ORIGIN_IP https://example.com/.
• Request reproduzieren: Minimalen Request mit curl -i oder curl -v ausführen; bei APIs zusätzlich Header/Body explizit setzen, z. B. curl -i -H "Accept: application/json" -H "Content-Type: application/json" --data '{}' https://api.example.com/resource.
• Caching ausschließen: Bei 3xx/4xx/5xx Cache-Verhalten prüfen, z. B. Cache-Control, Age, ETag; zum Testen Cache umgehen oder variieren, z. B. curl -i -H "Cache-Control: no-cache" https://example.com/.
• Timeout-Kette prüfen: Abstimmung zwischen Client-, CDN-, Load-Balancer- und App-Timeouts; bei 504 korrelierende Upstream-Logs mit Zeitstempeln und Request-ID abgleichen.
• REST-Semantik schärfen: Fehlerzustände konsistent codieren (z. B. 401 vs. 403, 404 vs. 410, 409 bei Versionskonflikten); bei 429 und 503 optional Retry-After setzen, um Retries steuerbar zu machen.

Sonderfälle aus der Praxis: Redirect-Ketten, Auth und CORS, Range/Conditional Requests, REST-APIs hinter Reverse Proxy/CDN und Fehlerbilder mit Querverweisen

Redirect-Ketten, Loop-Erkennung und Methodenwechsel

Redirects wirken oft trivial, werden in der Praxis aber durch Ketten, gemischte Protokolle und Caching-Regeln fehleranfällig. Typische Symptome sind wechselnde Statuscodes (z. B. 301→302→200), unerwartete Ziel-URLs oder Endlosschleifen, die Browser als „zu viele Weiterleitungen“ abbrechen. Technisch entscheidend sind Ziel-URL, Weiterleitungstyp, Cache-Header und die Frage, ob sich die HTTP-Methode während des Redirects ändert. Bei 301/302 wird ein POST je nach Client historisch teils zu GET umgeschrieben; 307/308 erhalten Methode und Body und sind für API-Requests daher häufig die sicherere Wahl.

Auth-Sonderfälle: 401 vs. 403, Sessions, Tokens und Browser-Prompts

Im Auth-Kontext entscheidet die korrekte Trennung zwischen „nicht authentifiziert“ und „nicht autorisiert“ über Debugbarkeit und Client-Verhalten. 401 Unauthorized signalisiert fehlende oder ungültige Authentifizierung und sollte bei HTTP-Authentifizierung fast immer einen WWW-Authenticate-Header enthalten. 403 Forbidden zeigt an, dass Authentifizierung vorhanden sein kann, die Berechtigung jedoch fehlt oder der Zugriff aus Policy-Gründen blockiert wird (z. B. IP-Block, WAF-Regel, fehlende Rollen).

Häufige Praxisprobleme entstehen, wenn Reverse Proxies Auth übernehmen und Upstreams dennoch eigene Auth-Checks durchführen, oder wenn Session-Cookies am Edge verloren gehen (Domain-, Path-, Secure-, SameSite-Attribute). Bei APIs mit Bearer Tokens führt eine ausgelaufene Signatur typischerweise zu 401, während ein gültiges Token ohne ausreichende Scopes sauber als 403 zurückgegeben wird. Für Rate-Limits ist 429 Too Many Requests mit Retry-After semantisch passender als ein generisches 403.

• 401 mit Challenge: Bei HTTP-Auth WWW-Authenticate: Basic realm="..." oder WWW-Authenticate: Bearer error="invalid_token" senden; ohne Challenge können Browser/Clients uneinheitlich reagieren.
• 403 gezielt begründen: Für APIs maschinenlesbare Fehlerobjekte liefern und Korrelation mit X-Request-ID oder traceparent ermöglichen; bei WAF/CDN-Sperren im Log die Rule-ID ablegen.
• Cookie-Fallen hinter Proxy: Set-Cookie-Attribute prüfen, insbesondere Secure bei HTTPS-Termination am Proxy und SameSite=None; Secure für Cross-Site-Flows; Domain/Path konsistent halten.
• 429 statt „verstecktes“ Throttling: Rate-Limits mit 429 und Retry-After kommunizieren; zusätzlich Header wie RateLimit-Limit und RateLimit-Remaining nur nutzen, wenn Clients diese erwarten.

CORS und Preflight: wenn 200 im Log steht, aber der Browser blockiert

CORS-Probleme erscheinen häufig als „Netzwerkfehler“, obwohl der Server formal erfolgreich antwortet. Auslöser ist meist ein fehlender oder falscher Access-Control-Allow-Origin-Header oder ein nicht erfüllter Preflight. Preflight-Requests verwenden OPTIONS und erwarten passende Antworten auf Access-Control-Request-Method und Access-Control-Request-Headers. Ein Backend kann dabei 200 liefern, während der Browser die Antwort verwirft, wenn Access-Control-Allow-Credentials und Origin-Regeln nicht konsistent sind.

Typische Fehlkonfigurationen betreffen Wildcards mit Credentials (nicht zulässig), fehlende Weitergabe der Origin durch Caches oder das „Verschlucken“ von OPTIONS durch Reverse Proxies. Auch Redirects im Preflight sind problematisch, weil Browser Preflight-Redirects restriktiv behandeln; deshalb sollten CORS-Endpunkte stabil ohne Umleitung erreichbar sein.

Range- und Conditional Requests: 206, 304, 412 und „mysteriöse“ 416

Teilantworten und Cache-Validierung erzeugen Statuscodes, die in Monitoring und Support häufig missverstanden werden. 206 Partial Content entsteht durch Range-Header (z. B. Videostreaming, Download-Resumes) und muss zu Content-Range und konsistenter Content-Length-Berechnung passen. 304 Not Modified ist kein Fehler, sondern die erwartete Antwort auf If-None-Match bzw. If-Modified-Since; dabei darf der Server keinen Response-Body senden.

412 Precondition Failed tritt auf, wenn Vorbedingungen wie If-Match scheitern und schützt vor Lost Updates (wichtig bei PUT/PATCH). 416 Range Not Satisfiable entsteht, wenn ein Client Bereiche anfordert, die zur Ressource nicht passen, häufig nach Dateiänderungen oder wenn ein CDN einen veralteten Content-Length-Stand cached. In diesen Fällen sollte die Ressource ETags korrekt versionieren und Proxies müssen Variationen über relevante Header respektieren.

• 206 korrekt bedienen: Accept-Ranges: bytes nur setzen, wenn Byte-Ranges zuverlässig unterstützt werden; zu jeder Range-Antwort Content-Range und passende ETag/Last-Modified liefern.
• 304 sauber ausspielen: Für starke Validatoren ETag bevorzugen; bei 304 keine Entity-Header inkonsistent ändern, sonst drohen Cache-Divergenzen zwischen Browser, Proxy und CDN.
• 412 gezielt nutzen: Bei konkurrierenden Schreibzugriffen If-Match mit ETag verlangen; ohne Precondition lieber 428 Precondition Required erwägen, wenn Clients damit umgehen können.
• 416 analysieren: Client-Resumes prüfen; bei CDNs Cache-Key und Invalidation kontrollieren; bei dynamischen Dateien Range-Requests ggf. deaktivieren oder stabil versionierte URLs verwenden.

REST-APIs hinter Reverse Proxy/CDN: „richtig“ am Origin, „falsch“ am Edge

Zwischen Client und Origin liegen oft Load Balancer, Ingress Controller, API-Gateways und CDNs, die Statuscodes transformieren oder verdecken. Ein klassisches Muster ist 502 Bad Gateway am Proxy, während der Upstream intern z. B. 500 oder gar korrekt 200 antwortet, aber die Verbindung abbricht. 504 Gateway Timeout entsteht, wenn der Proxy-Timeout kleiner als der Upstream-Processing-Timeout ist; der Origin arbeitet dann weiter, während der Client bereits eine 504 sieht.

Für REST-APIs ist außerdem relevant, ob das Gateway Responses cached, Header entfernt oder Kompression/Chunking verändert. Fehlende Weitergabe von Authorization oder das Caching von 401/403 am Edge erzeugt schwer zu reproduzierende Zustände. Korrekte Protokollierung erfordert deshalb eine durchgängige Request-ID und die Erfassung beider Perspektiven (Edge und Origin) inklusive Upstream-Status, Verbindungsfehler und Latenzen.

Fehlerbilder mit Querverweisen: schnelle Zuordnung über Muster

Viele Vorfälle zeigen nicht „den einen“ Statuscode, sondern Kombinationen über mehrere Schichten. Ein Browser meldet etwa CORS-Blockade, während das Backend 200 liefert; ein Monitoring sieht 5xx am Edge, obwohl der Origin gesund ist; oder ein Client interpretiert 302 als Erfolg und ignoriert, dass ein API-Call stillschweigend auf eine Login-Seite umgeleitet wurde. Für eine belastbare Diagnose sollten Statuscode, Location, relevante Header und die Route (Edge/Origin) gemeinsam betrachtet werden.

• „Zu viele Weiterleitungen“: Korrelation mit 301/302/307/308, Prüfung von Schema/Host-Normalisierung, Cookies und Proxy-Signalen wie X-Forwarded-Proto.
• „CORS error“ bei scheinbar erfolgreichem Request: Preflight OPTIONS in Logs suchen; Response-Header Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers, Vary: Origin prüfen; Redirects im Preflight vermeiden.
• Download bricht ab / Video stottert: Auftreten von 206 und 416 prüfen; Änderungen an Asset-Versionierung (ETag/URL) und CDN-Cache; bei dynamischen Inhalten Range-Unterstützung verifizieren.
• API-Clients sehen HTML statt JSON: Unerwünschte Redirects auf Login (häufig 302) oder WAF-Blockseiten (oft 403) identifizieren; Content-Negotiation über Accept: application/json konsistent behandeln und Fehlerantworten im gleichen Format liefern.
• Edge 5xx, Origin 2xx: Upstream-Timeouts, Body-Größenlimits, Header-Sanitizing und Kompressions-/Chunking-Unterschiede zwischen Edge und Origin prüfen; Request-ID über X-Request-ID end-to-end durchreichen.