HTTP-Statuscodes

Die Klassenziffer trägt den Vertrag

Jede HTTP-Antwort beginnt mit einem dreistelligen Code, und die erste Ziffer ist der einzige Teil, den ein Client verstehen muss. RFC 9110 ist da explizit: Ein Client, der einen unbekannten 499 erhält, muss ihn genau wie einen 400 behandeln, weil die Klasse die Semantik festlegt und die übrigen zwei Ziffern sie nur verfeinern. Diese Regel hält das Protokoll erweiterbar. Ein 2005 geschriebener Proxy kann einen 451 korrekt weiterleiten, ohne zu wissen, was rechtliche Zensur ist.

Die fünf Klassen teilen sauber auf, wer für das Weitere verantwortlich ist. Ein 1xx ist eine Zwischenantwort, also kommt die echte Antwort noch und die Verbindung bleibt offen. Ein 2xx bedeutet, die Anfrage war erfolgreich und der Client kann stoppen. Ein 3xx gibt eine Umleitung zurück, also sollte der Client es woanders erneut versuchen. Ein 4xx gibt der Anfrage die Schuld, also wird sie unverändert wiederholt erneut fehlschlagen. Ein 5xx gibt dem Server die Schuld, also könnte die identische Anfrage beim Wiederholen gelingen. Deshalb knüpft Retry-Logik an die Klasse und nicht an den konkreten Code: Ein 503 erneut zu versuchen ist vernünftig, ein 403 ein Bug.

Codes, die regelmäßig verwechselt werden

Der Unterschied zwischen 301 und 308 oder 302 und 307 ist nicht stilistisch. Das ältere Paar erlaubt einem Client, beim Folgen der Umleitung ein POST in ein GET umzuschreiben, was Browser historisch getan haben. Das neuere Paar verbietet dieses Umschreiben und bewahrt sowohl Methode als auch Body. Wenn du einen Formular-Endpunkt mit 301 verschiebst, werden manche Clients die Übermittlung stillschweigend in ein GET umwandeln und die Nutzlast fallen lassen. Verwende 308 oder 307 für alles, was nicht idempotent ist.

401 und 403 werden ähnlich verwechselt. Eine 401 bedeutet, die Anfrage war nicht authentifiziert und muss mit einer WWW-Authenticate-Herausforderung eintreffen, die dem Client sagt, wie er es mit Anmeldedaten erneut versucht. Eine 403 bedeutet, der Server wusste, wer du bist, und weigert sich dennoch. Eine 401 ohne Challenge-Header zu senden verletzt die Spezifikation, und eine 403 zu senden, wenn der Nutzer schlicht vergessen hat, sich einzuloggen, macht den Fehler viel schwerer zu debuggen.

Die 4xx-Klasse enthält auch ein wirklich nützliches Paar: 400 gegenüber 422. Eine 400 bedeutet, die Anfrage ließ sich gar nicht parsen, also ist die Syntax kaputt. Eine 422 bedeutet, die Syntax wurde fehlerfrei geparst, aber der Inhalt bestand die Validierung nicht. Diese Trennung verwandelt ein undurchsichtiges Fehlschlagen in ein handhabbares für API-Clients.

Reason-Phrasen sind nur für Menschen

Der Text neben dem Code, wie Not Found oder I'm a teapot, ist die Reason-Phrase. HTTP/1.1 sendet sie in der Statuszeile, aber HTTP/2 und HTTP/3 entfernten sie ganz, also trägt eine moderne Verbindung oft die Zahl ohne Phrase überhaupt. Nichts in einem Client darf je auf dieser Zeichenfolge verzweigen. Sie existiert, damit ein Mensch, der ein Protokoll oder eine Roh-Ablaufverfolgung liest, ohne Nachschlagetabelle sieht, was geschah.

Manche Codes sind zudem stärker eingeschränkt, als sie wirken. Eine 204 und eine 304 dürfen keinen Nachrichten-Body enthalten, also erzeugt ein Vermittler, der einen hinzufügt, eine ungültige Antwort. Eine HEAD-Antwort trägt unabhängig vom Code nie einen Body. Diese Rahmenregeln zählen, weil ein Body, wo keiner erwartet wird, die Wiederverwendung der Verbindung desynchronisiert, was sich als bizarre überkreuzte Korruption statt als offensichtlicher Fehler zeigt.