HTTP-Fehlercodes, und wie Sie erkennen, welchen Sie tatsächlich vor sich haben

Jeder HTTP-Fehler ist eine einzeilige Antwort auf eine Frage, die niemand laut gestellt hat: was ist mit meiner Anfrage passiert? Die Zahl ist die ganze Antwort, und sie ist bewusst knapp, also besteht die meiste Arbeit darin, zu wissen, welche Frage jede Zahl beantwortet.

Dafür ist diese Seite da. Keine Liste aller sechzig-und-ein-paar Statuscodes, von denen Sie die meisten nie sehen werden, sondern das gute Dutzend, das tatsächlich bei Menschen ankommt, geordnet danach, was es Ihnen darüber sagt, wo der Fehler lag.

Die eine Unterscheidung, auf die es ankommt

Die erste Ziffer ist der einzige Teil des Codes, den Sie sich merken müssen.

4xx

Der Server hat Sie verstanden und weigert sich, oder er konnte das Angekommene nicht parsen. Das Problem steckt in der Anfrage

5xx

Die Anfrage war in Ordnung. Der Server hat keine Antwort zustande gebracht, oder wollte nicht

Alles andere folgt daraus. Ein 4xx schickt Sie zu dem, was gesendet wurde: die URL, die Header, der Body, die Anmeldedaten. Ein 5xx schickt Sie in die Logs des Servers, und wenn es nicht Ihr Server ist, können Sie wenig mehr tun, als es gut zu melden.

Das Wort “Client” in “Client-Fehler” ist der Punkt, an dem Leute den Faden verlieren, deshalb sei es deutlich gesagt: der Client sind nicht Sie. Der Client ist die Software, die die Anfrage zusammengesetzt hat, und auf einer modernen Website ist das fast immer das JavaScript der Seite selbst. Ein 4xx auf einer fremden Website ist meist deren Fehler mit Ihrem Namen darauf.

Die 4xx-Codes, denen Sie wirklich begegnen

400 Bad Request ist der Server, der das Angekommene überhaupt nicht parsen kann. Es ist der einzige in dieser Familie, bei dem es um die Form der Anfrage geht statt um Berechtigung oder Existenz. Ein fehlerhafter Body, ein fehlender Content-Type, eine nicht maskierte URL. Es gibt genau eine Version, die Sie selbst beheben können: ein zu groß gewordener Cookie-Block, was ein privates Fenster in Sekunden bestätigt.

401 und 403 sind die beiden, die ständig vertauscht werden. 401 heißt, der Server weiß nicht, wer Sie sind, und will Anmeldedaten. 403 heißt, er weiß genau, wer Sie sind, und die Antwort ist trotzdem nein. Bessere Anmeldedaten beheben das erste und niemals das zweite.

404 Not Found braucht keine Erklärung, aber eines lohnt sich zu wissen: ein 404 auf eine Anfrage, die die Seite im Hintergrund gemacht hat, statt in der Adresszeile, bedeutet meist, dass ein Build oder ein Deploy eine Datei verloren hat, und nicht, dass sich jemand vertippt hat.

429 Too Many Requests ist der einzige Statuscode, bei dem es um Ihr Verhalten geht statt um den Server oder die Ressource. Er ist außerdem der eine Fehler, bei dem ein erneuter Versuch alles schlimmer macht, denn ein Retry ist eine weitere Anfrage, die der Limiter zählt.

Die 5xx-Codes, die identisch aussehen und Verschiedenes bedeuten

Alle vier sagen “bei uns”, und sie auseinanderzuhalten entscheidet, wo zuerst jemand nachsieht.

500 Internal Server Error

Die Anwendung lief, und ihr eigener Code ist gescheitert. Eine unbehandelte Ausnahme. Sie hat geantwortet, und die Antwort war ein Fehler, den sie selbst gemacht hat

502 Bad Gateway

Ein vorgelagerter Server bekam eine unbrauchbare Antwort von der Anwendung dahinter. Der Fehler liegt zwischen zwei Servern

503 Service Unavailable

Etwas hat entschieden, Sie nicht zu bedienen. Wartung, Kapazität, ein Rate Limiter, oder nichts Gesundes zum Weiterleiten

504 Gateway Timeout

Die Anwendung hat nie rechtzeitig geantwortet. Der vorgelagerte Server hat aufgegeben

Die nützliche Kurzfassung: ein 500 ist Code, der beim Laufen kaputtgeht, ein 502 ist ein Proxy, der keine gute Antwort bekommen hat, ein 504 ist die Anwendung, die zu langsam ist, und ein 503 ist der einzige, der meistens Absicht ist. Diese letzte Unterscheidung zählt mehr, als sie klingt: ein 503 trägt oft einen Retry-After-Header, der genau sagt, wann man wiederkommen soll, und fast niemand liest ihn.

Die Fehler, die gar keine Statuscodes sind

Einige der häufigsten Fehlschläge erzeugen nie einen Statuscode, und genau deshalb sind sie verwirrend. Die Anfrage ist nicht gescheitert; sie ist nie fertig geworden.

TypeError: Failed to fetch ist JavaScripts uninformativster Fehler. Es gibt keinen Status zu lesen, weil die Anfrage nie weit genug kam, um einen zu haben.

CORS-Fehler sind der Browser, der sich weigert, Ihrem Code eine Antwort zu geben, die sehr wohl angekommen ist. Der Server hat einwandfrei geantwortet; er hat nur nicht gesagt, dass Ihre Herkunft erlaubt ist.

ERR_CONNECTION_REFUSED, RESET, CLOSED und TIMED_OUT passieren ganz unterhalb von HTTP. Jeder benennt, wie weit die Verbindung kam, bevor sie starb, und das ist die halbe Diagnose geschenkt.

Mixed Content ist der Browser, der eine unsichere Ressource auf einer sicheren Seite blockiert. Im Netzwerk ist gar nichts fehlgeschlagen; es wurde eine Regel angewendet.

Einen lesen, der nicht Ihrer ist

Wenn Sie Besucher sind und nicht derjenige, der es beheben kann, trennen drei Prüfungen die meisten Fälle und dauern unter einer Minute.

Einmal neu laden. Eine ganze Reihe von 500ern und 503ern ist ein einzelner schlechter Moment. Wenn es sich klärt, gibt es nichts zu verfolgen.

Ein privates Fenster probieren. Das ist der Test für die Cookie-und-Header-Familie: ein 400, der im Privatfenster verschwindet, war ein zu großer Cookie-Block, und einer, der bleibt, war nie Ihrer.

Ein anderes Netzwerk probieren. Ein Handy im Mobilfunknetz beantwortet die Frage, die ein Rate Limiter aufwirft. Folgt Ihnen der Fehler überallhin, ist es Ihr Konto oder die Website; verschwindet er, war es die Adresse, von der Sie kamen. Das ist dieselbe Frage wie Ihren Bug von deren Ausfall zu unterscheiden, nur schnell gestellt.

Warum der Code allein selten reicht, um etwas zu beheben

Jeder Fehler oben ist eine Zusammenfassung, aus der die Belege entfernt wurden. Das ist kein Zufall: ein 500 ist mit Absicht vage, weil der Stacktrace auf dem Server bleibt, und ein 400 wird Ihnen nicht sagen, welcher Header ihn gestört hat. Der Code benennt die Kategorie und verschweigt den Fall.

“Ich habe einen 500 bekommen” ist also eine Meldung, die einem Entwickler fast nichts sagt, und bis jemand nachsieht, ist die gescheiterte Anfrage weg. Was einen schnell schließt, ist die gescheiterte Anfrage selbst, ihre genaue Zeit, und was die Person gerade tat.

Das Netzwerkprotokoll ist der Ort, an dem ein Statuscode aufhört, eine Kategorie zu sein, und ein Fall wird: die Anfrage, die den Fehler bekam, ihre Header und ihr Body, und die genaue Minute, so dass derjenige, der sie aufnimmt, sie gegen ein Serverlog halten kann, statt zuerst das Ganze nachzustellen.

In einem Absatz

Die erste Ziffer ist die Unterscheidung, auf die es ankommt: ein 4xx heißt, das Problem steckt in der Anfrage, ein 5xx heißt, der Server hat keine Antwort zustande gebracht, und der von einem 4xx beschuldigte “Client” ist meist das JavaScript der Website und nicht Sie. Innerhalb der 4xx geht es beim 400 um die Form der Anfrage, bei 401 und 403 um Identität gegen Berechtigung, und beim 429 darum, wie oft Sie gefragt haben. Innerhalb der 5xx ist 500 Code, der kaputtgeht, 502 ein Proxy mit einer schlechten Antwort, 504 nichts, was rechtzeitig antwortet, und 503 der einzige, der meist eine Entscheidung ist. Die Fehler ganz ohne Statuscode - failed to fetch, CORS, ERR_CONNECTION_*, Mixed Content - verwirren am meisten, weil die Anfrage nie fertig wurde statt zu scheitern. Welchen Sie auch haben: der Code benennt die Kategorie und verschweigt den Fall, also sichern Sie die gescheiterte Anfrage, solange Sie sie noch haben.