HTTP-Statuscodes: Was sie bedeuten und wann du sie verwendest
Jenseits von 200 und 404. Ein praktischer Leitfaden zu Statuscodes für API-Entwickler.
Deine API gibt 200 zurück. Der Response-Body sagt {"error": "Not found"}.
Das ist falsch. Statuscodes existieren aus einem Grund. Verwende sie richtig.
Die fünf Kategorien
1xx — Informativ. In der Praxis selten gesehen.
2xx — Erfolg. Die Anfrage hat funktioniert.
3xx — Umleitung. Geh woanders hin.
4xx — Client-Fehler. Du hast etwas falsch gemacht.
5xx — Server-Fehler. Wir haben etwas falsch gemacht.
Die Codes, die du tatsächlich verwenden wirst
Erfolg (2xx)
200 OK — Standard-Erfolg. Verwende für GET-Anfragen, die Daten zurückgeben.
201 Created — Ressource wurde erstellt. Verwende nach erfolgreichem POST, das etwas erstellt.
204 No Content — Erfolg, aber nichts zurückzugeben. Verwende für DELETE oder Updates, die keine Daten zurückgeben.
Client-Fehler (4xx)
400 Bad Request — Fehlerhafte Anfrage. Ungültiges JSON, fehlende Pflichtfelder, falsche Datentypen.
401 Unauthorized — Keine Authentifizierung. Nutzer muss sich anmelden.
403 Forbidden — Authentifiziert, aber nicht erlaubt. Nutzer existiert, hat aber keine Berechtigung.
404 Not Found — Ressource existiert nicht. Der Klassiker.
409 Conflict — Anfrage steht im Konflikt mit aktuellem Zustand. Doppelter Nutzername, Versions-Mismatch.
422 Unprocessable Entity — Syntaktisch korrekt, aber semantisch falsch. Valides JSON, aber Business-Regeln verletzt.
429 Too Many Requests — Rate-limitiert. Verlangsame dich.
Server-Fehler (5xx)
500 Internal Server Error — Generischer Server-Fehler. Etwas ist abgestürzt.
502 Bad Gateway — Upstream-Server fehlgeschlagen. Dein Server ist ok, aber etwas, von dem er abhängt, nicht.
503 Service Unavailable — Temporär down. Wartung oder Überlastung.
504 Gateway Timeout — Upstream-Server hat nicht rechtzeitig geantwortet.
Häufige Fehler
200 mit Fehler im Body. Wenn es ein Fehler ist, verwende einen Fehler-Statuscode. Zwinge Clients nicht, den Body zu parsen, um zu wissen, ob es erfolgreich war.
500 für Validierungsfehler. Nutzer hat schlechte Daten eingereicht? Das ist 400 oder 422, nicht 500. Server ist nicht kaputt – die Anfrage ist es.
401 vs. 403 Verwirrung. 401 bedeutet „Wer bist du?" 403 bedeutet „Ich weiß, wer du bist, aber nein."
404 für alles. „Nicht gefunden" ist nicht immer die richtige Antwort. Falsche Methode? 405. Rate-limitiert? 429.
APIs designen
Sei spezifisch. Clients können spezifische Fehler intelligent behandeln. Generische Fehler bedeuten generische Behandlung.
Füge Fehlerdetails im Body hinzu:
{
"error": "validation_failed",
"message": "Email format is invalid",
"field": "email"
}
Der Statuscode sagt, welche Problemkategorie. Der Body erklärt spezifisch.
Statuscodes als Client behandeln
2xx — Response parsen, normal fortfahren.
4xx — Dein Fehler. Loggen, Nutzer anzeigen, Anfrage korrigieren.
5xx — Server-Fehler. Vielleicht mit Backoff wiederholen. Vielleicht alarmieren.
3xx — Umleitungen automatisch folgen (die meisten HTTP-Clients tun das).
Prüfe nicht nur auf 200. Prüfe auf Erfolg (2xx) und behandle andere Fälle angemessen.
Statuscodes sind Kommunikation. Verwende sie korrekt, und APIs werden selbstdokumentierend. Missbrauche sie, und Debugging wird zum Ratespiel.