Warum Statuscodes Ihr erstes Diagnosesignal sind
Jede HTTP-Antwort trägt einen dreistelligen Statuscode, und diese eine Zahl ist oft das schnellste Diagnosesignal, das Sie haben. Noch bevor Sie eine Logdatei oder ein Tracing-Dashboard öffnen, sagt Ihnen der Statuscode bereits, ob die Anfrage erfolgreich war, umgeleitet wurde, wegen eines Client-Fehlers abgelehnt wurde oder an etwas auf Ihrem Server gescheitert ist. Statuscodes richtig zu lesen — und sie systematisch zu überwachen — ist eine der günstigsten und wirkungsvollsten Gewohnheiten in der API-Observability.
Das Problem: Die meisten Teams behandeln Statuscodes binär: „200 ist gut, alles andere ist schlecht.“ Dieses Denkmodell übersieht entscheidende Unterschiede. Ein 404 auf einer vertippten URL ist normales Internetrauschen; ein 404 auf einem Endpunkt, der gestern noch funktionierte, ist eine Regression. Ein 401-Anstieg direkt nach einer Token-Rotation ist erwartbar; derselbe Anstieg um 3 Uhr morgens ohne Deployment ist ein Vorfall. Dieser Leitfaden schlüsselt jeden Statuscode-Bereich auf, damit Ihr Monitoring diese Situationen unterscheiden kann.
2xx Erfolg: Was „funktioniert“ wirklich bedeutet
200 OK ist die Standard-Erfolgsantwort, aber nicht die einzige, die es zu unterscheiden lohnt. 201 Created bestätigt, dass eine Ressource tatsächlich persistiert wurde — wenn Ihre API nach einem POST 200 statt 201 zurückgibt, ist das ein Zeichen, dass Ihre Antwortsemantik von der Konvention abweicht, die Ihre Clients erwarten. 204 No Content ist korrekt für erfolgreiche Anfragen ohne Rückgabewert, etwa ein DELETE; stattdessen ein 200 mit leerem Body zu senden ist eine häufige, aber harmlose Inkonsistenz, die sich zu standardisieren lohnt.
Die Falle bei 2xx-Codes ist die Annahme, sie würden Korrektheit beweisen. Ein 200 OK mit einem fehlerhaften oder leeren JSON-Body bleibt in jedem Dashboard ein 2xx — genau deshalb reicht Statuscode-Monitoring allein nicht aus. Kombiniert mit Content-Assertions fangen Sie die Fehler ab, die ein Statuscode allein niemals aufdecken wird.
3xx Weiterleitungen: Wenn Erfolg nicht die ganze Geschichte ist
Weiterleitungen sind in JSON-APIs selten, auf webfähigen Endpunkten aber häufig — und sie verdienen mehr Aufmerksamkeit, als sie üblicherweise bekommen. 301 Moved Permanently und 308 Permanent Redirect weisen Clients und Suchmaschinen an, die gespeicherte URL zu aktualisieren; wenn ein Monitor endlos auf einen 301 trifft, ohne je ein finales 200 zu erreichen, ist die Weiterleitungskette defekt oder zirkulär. 302 Found und 307 Temporary Redirect sollten sich beim nächsten Sprung in ein 2xx auflösen — ein Monitor, der Weiterleitungen nicht folgt, meldet fälschlicherweise einen Ausfall für einen völlig gesunden Endpunkt.
304 Not Modified ist ein Sonderfall, den es getrennt zu verfolgen lohnt: Er bestätigt, dass Ihre Caching-Schicht (ETags, bedingte GETs) funktioniert. Ein plötzlicher Rückgang der 304-Antworten, ersetzt durch volle 200-Payloads, bedeutet meist, dass ein Caching-Header in einem kürzlichen Deployment regressiert ist — ein Performance-Problem, lange bevor es ein Ausfall wird.
4xx Client-Fehler: Wessen Schuld ist es wirklich?
4xx-Codes heißen „Client-Fehler“, aber dieses Etikett führt beim Monitoring in die Irre — ein plötzlicher 4xx-Anstieg ist sehr oft Ihr Fehler. Ein 400 Bad Request-Anstieg direkt nach einem Deployment bedeutet meist, dass sich eine Validierungsregel geändert hat und bestehende Clients ihr nun nicht mehr genügen. 401 Unauthorized und 403 Forbidden sind vereinzelt erwartbar (falsche Zugangsdaten, abgelaufene Tokens), aber ein plötzlicher flächendeckender Anstieg deutet auf einen defekten Auth-Dienst oder ein fehlkonfiguriertes Gateway hin — nicht darauf, dass sich Tausende Nutzer plötzlich vertippen.
404 Not Found verdient eine Baseline statt eines harten Alarms — das Internet ist voller Scanner und veralteter Links. Entscheidend ist die Veränderung: Wenn ein Endpunkt, der bisher 200 lieferte, plötzlich 404 zurückgibt, ist das eine Routing-Regression, kein Hintergrundrauschen. 429 Too Many Requests ist der eine 4xx-Code, bei dem Sie für kritische Integrationen fast immer alarmieren sollten — er bedeutet, dass legitimer Traffic gedrosselt wird, und wenn er anhält, trifft er genau die Nutzer, die Ihnen am wichtigsten sind.
5xx Server-Fehler: Die Codes, die Sie wecken sollten
5xx-Codes sind eindeutig: Etwas auf Ihrer Seite der Leitung ist gescheitert. 500 Internal Server Error ist der generische Sammelbegriff — nützlich als Rauchmelder, aber Sie sollten immer in den Logs nach der eigentlichen Exception dahinter suchen. 502 Bad Gateway bedeutet, dass Ihr Load Balancer oder Reverse Proxy keine gültige Antwort von einem vorgelagerten Dienst bekommen hat — prüfen Sie die Gesundheit dessen, was hinter Ihrem Gateway liegt, nicht das Gateway selbst. 503 Service Unavailable zeigt meist an, dass der Dienst Traffic absichtlich ablehnt (Überlastschutz, Wartungsmodus oder ein ausgelöster Circuit Breaker), während 504 Gateway Timeout bedeutet, dass der Upstream überhaupt nicht rechtzeitig geantwortet hat.
Diese drei — 502, 503, 504 — werden häufig verwechselt, zeigen aber auf unterschiedliche Schichten Ihres Stacks. Wer auf „5xx“ als einen einzigen Topf alarmiert, verschenkt den Diagnosewert, den der konkrete Code bereits kostenlos liefert. Ein Monitoring, das den exakten Code anzeigt statt nur „5xx erkannt“, verkürzt die Triage von Minuten auf Sekunden.
