Statuscodes verstehen

Jede HTTP-Antwort trägt einen dreistelligen Statuscode. Die erste Ziffer ordnet ihn einer von fünf Klassen zu und sagt dem Client grob, was passiert ist. Für eine API ist der Statuscode der wichtigste Vertrag: Clients und Monitoring werten ihn maschinell aus, bevor sie überhaupt in den Antwort-Body schauen.

1xx (Informational): vorläufige Zwischenantworten, die Verarbeitung läuft noch. Beispiel 100 Continue: Der Client darf mit dem Senden des Request-Bodys fortfahren. 1xx-Antworten enthalten laut RFC 9110 keinen Inhalt und spielen im API-Alltag meist keine Rolle.

2xx (Erfolg): Die Anfrage wurde verstanden und akzeptiert.

• 200 OK: Standarderfolg. Bei GET liegt die Ressource im Body.
• 201 Created: Eine neue Ressource wurde angelegt, typisch nach POST oder manchen PUT. Sinnvoll mit einem Location-Header auf die neue Ressource.
• 204 No Content: Erfolg ohne Body, etwa nach einem DELETE oder einem Update, das nichts zurückgeben muss. Header können trotzdem nützlich sein.

3xx (Umleitung): Es sind weitere Schritte nötig, meist ein Wechsel der URL.

• 301 Moved Permanently: Die Ressource liegt dauerhaft unter einer neuen URL (im Location-Header). Clients und Caches sollten die neue URL übernehmen.
• 302 Found: nur temporär verschoben. Die ursprüngliche URL bleibt für künftige Anfragen maßgeblich.

4xx (Client-Fehler): Der Fehler liegt beim Aufrufer, etwa falsche Daten oder fehlende Rechte. Ein Wiederholen mit identischer Anfrage hilft hier in der Regel nicht.

• 400 Bad Request: Die Anfrage ist fehlerhaft, etwa ungültiges JSON oder fehlende Pflichtfelder.
• 401 Unauthorized: Es fehlen gültige Authentifizierungsdaten. Semantisch bedeutet das eigentlich nicht authentifiziert. Der Server muss laut RFC 9110 einen WWW-Authenticate-Header senden. Der Client kann es mit gültigen Credentials erneut versuchen.
• 403 Forbidden: Der Server hat die Anfrage verstanden, verweigert sie aber. Der Nutzer ist bekannt, hat aber keine Zugriffsrechte. Erneutes Anmelden hilft nicht.
• 404 Not Found: Ressource nicht gefunden. Bei APIs auch möglich, wenn der Endpunkt existiert, die konkrete Ressource aber nicht.
• 429 Too Many Requests: Rate Limiting, der Client hat in zu kurzer Zeit zu viele Anfragen gesendet.

5xx (Server-Fehler): Der Server kennt die Anfrage als gültig, kann sie aber nicht erfüllen.

• 500 Internal Server Error: unerwarteter, generischer Serverfehler.
• 503 Service Unavailable: Der Server ist nicht bereit, etwa wegen Wartung oder Überlast. Oft sinnvoll mit einem Retry-After-Header.

Sicherheitsrelevant: 401 vs. 403. 401 heißt Wer bist du? (Authentifizierung fehlt oder ist ungültig). 403 heißt Ich weiß, wer du bist, aber du darfst das nicht (Authentifizierung ok, Autorisierung fehlt). Diese Trennung sauber umzusetzen ist wichtig: Ein 403 bestätigt indirekt, dass eine Ressource existiert, was bei sensiblen Endpunkten ungewollt Information preisgeben kann. Wer das vermeiden will, antwortet bei verbotenem Zugriff bewusst mit 404, um die Existenz zu verschleiern.

POST /api/orders HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{ "productId": 42, "quantity": 2 }

--- mögliche Antworten ---
201 Created            Location: /api/orders/1001   (Bestellung angelegt)
400 Bad Request        (quantity fehlt oder ist kein Zahlenwert)
401 Unauthorized       WWW-Authenticate: Bearer    (Token fehlt/abgelaufen)
403 Forbidden          (Token gültig, aber keine Bestellrechte)
429 Too Many Requests  Retry-After: 30
503 Service Unavailable Retry-After: 120

Ein POST-Request und typische Statuscodes, die eine API darauf zurückgeben kann.

Quellen

• HTTP response status codes MDN Web Docs
• RFC 9110: HTTP Semantics RFC Editor / IETF