HTTP-Statuscodes richtig verwenden: die erste Verzweigung des Clients

Worum es geht

RFC 9110 definiert die fünf Klassen und die einzelnen Codes; ein Client muss die Klasse an der ersten Ziffer erkennen und einen unbekannten Code wie den x00-Code seiner Klasse behandeln. Einige Unterscheidungen entscheiden in der Praxis: 401 bedeutet fehlende oder ungültige Anmeldedaten, und der Server muss dabei einen WWW-Authenticate-Header senden; 403 bedeutet, die Anmeldung ist in Ordnung, aber die Handlung ist nicht erlaubt. 404 sagt, das Ziel existiert nicht – oder der Server will seine Existenz nicht preisgeben. 409 meldet einen Konflikt mit dem aktuellen Zustand, 412 eine gescheiterte Vorbedingung wie If-Match, 422 eine syntaktisch korrekte, aber inhaltlich nicht verarbeitbare Anfrage. RFC 6585 ergänzt 428 (Vorbedingung erforderlich) und 429 (zu viele Anfragen), Letzteres wahlweise mit Retry-After; 503 ist vorübergehende Nichtverfügbarkeit, ebenfalls mit Retry-After, wo die Wartezeit berechenbar ist.

Warum es wichtig ist

Ein Client sieht den Code, bevor er den Körper parst; Bibliotheken, Proxys und Caches verzweigen nur darauf. Ein 503 oder 429 wird von vielen Clients wiederholt, ein 400 oder 422 nicht; ein 304 spart die Übertragung, ein 201 liefert die Adresse des Neuen. Ein Agent, der eine API aus der Dokumentation heraus bedient, braucht diese Konvention, um nicht bei jedem Fehler zu raten – und um nach einem Timeout nicht eine Anfrage zu wiederholen, die längst gewirkt hat.

So wird es angewendet

• Jede Fehlerklasse der Domäne genau einem Code und einem maschinenlesbaren Problemtyp zuordnen; die Tabelle gehört in die API-Dokumentation.
• Erzeugen mit 201 und Location oder der Kennung im Körper beantworten; erfolgreiches Löschen und Widerrufen mit 204 ohne Körper.
• 400 für syntaktisch kaputte Eingaben, 422 für inhaltlich ungültige – oder nur eines von beiden, aber durchgängig.
• Vorbedingungen mit If-Match und Entity-Tags verlangen und mit 412 beantworten; wer sie erzwingen will, antwortet auf Anfragen ohne Vorbedingung mit 428.
• Retry-After bei 429 und 503 senden, wann immer die Wartezeit bekannt ist; Clients und Agenten halten sich daran, statt sofort zu wiederholen.
• Umleitungen in APIs mit 307 oder 308, die Methode und Körper erhalten; bei 301 und 302 darf ein Client laut RFC 9110 aus historischen Gründen POST in GET umwandeln.

Stolpersteine

404 zum Verbergen von Berechtigungsentscheidungen ist legitim, muss aber konsequent sein, sonst verrät die Abweichung die Existenz. Eigene Codes ausserhalb der registrierten Bereiche verwirren Zwischenstationen. 200 mit {"error": ...} im Körper wird gecacht, nicht wiederholt und vom Monitoring als Erfolg gezählt.

Teilerfolg bei Stapelanfragen

Eine Anfrage, die mehrere Elemente verarbeitet, hat mehrere Ergebnisse. Der Statuscode beschreibt die Anfrage als Ganzes: 200 (oder 207 Multi-Status nach RFC 4918), wenn sie angenommen und verarbeitet wurde, 4xx nur, wenn sie als Ganzes ungültig war. Jedes Element trägt seinen eigenen Status und gegebenenfalls sein Problemobjekt im Antwortkörper, an einer dokumentierten Stelle; GraphQL verfährt genauso mit Feldfehlern neben data. Das Monitoring zählt Elementfehler getrennt von Anfragefehlern, damit ein 200 mit neunzig Prozent gescheiterten Elementen nicht als Erfolg durchgeht. Für alles andere bleibt die Regel des Artikels: Ein Fehler, der die ganze Anfrage betrifft, gehört in den Statuscode, nicht in ein 200.