Waarom statuscodes je eerste diagnosesignaal zijn
Elke HTTP-respons draagt een driecijferige statuscode, en dat ene getal is vaak het snelste diagnosesignaal dat je hebt. Nog voordat je een logbestand of tracing-dashboard opent, vertelt de statuscode je al of het verzoek slaagde, werd omgeleid, werd geweigerd door iets aan de clientkant, of faalde door iets op je server. Statuscodes correct lezen — en ze systematisch monitoren — is een van de goedkoopste en meest waardevolle gewoontes in API-observability.
Het probleem is dat de meeste teams statuscodes binair behandelen: "200 is goed, al de rest is fout." Dat denkmodel mist cruciale nuances. Een 404 op een verkeerd getypte URL is normale internetruis; een 404 op een endpoint dat gisteren nog werkte, is een regressie. Een piek in 401's vlak na een tokenrotatie is verwacht; dezelfde piek om 3 uur 's nachts zonder deployment is een incident. Deze gids ontleedt elke statuscodereeks zodat je monitoring die situaties uit elkaar kan houden.
2xx Succes: wat "het werkt" echt betekent
200 OK is de standaard succesrespons, maar niet de enige die het onderscheiden waard is. 201 Created bevestigt dat een resource daadwerkelijk is opgeslagen — als je API na een POST 200 in plaats van 201 teruggeeft, is dat een teken dat je responssemantiek is afgedreven van de conventie die je clients verwachten. 204 No Content is correct voor geslaagde verzoeken zonder terug te geven inhoud, zoals een DELETE; in plaats daarvan een 200 met lege body sturen is een veelvoorkomende maar onschuldige inconsistentie die het standaardiseren waard is.
De valkuil bij 2xx-codes is aannemen dat ze correctheid bewijzen. Een 200 OK met een misvormde of lege JSON-body blijft in elk dashboard een 2xx — precies daarom volstaat statuscode-monitoring alleen niet. Gecombineerd met content-assertions vang je de fouten op die een statuscode alleen nooit zal onthullen.
3xx Redirects: wanneer succes niet het hele verhaal is
Redirects zijn zeldzaam in JSON-API's maar gebruikelijk op webgerichte endpoints, en ze verdienen meer aandacht dan ze meestal krijgen. 301 Moved Permanently en 308 Permanent Redirect vertellen clients en zoekmachines om de opgeslagen URL bij te werken; als een monitor eindeloos een 301 blijft raken zonder ooit een finale 200 te bereiken, is de redirectketen kapot of circulair. 302 Found en 307 Temporary Redirect horen bij de volgende sprong op te lossen in een 2xx — een monitor die redirects niet volgt, meldt ten onrechte een storing voor een perfect gezond endpoint.
304 Not Modified is een speciaal geval dat apart volgen waard is: het bevestigt dat je cachinglaag (ETags, conditionele GET's) werkt. Een plotselinge daling van 304-responsen, vervangen door volledige 200-payloads, betekent meestal dat een caching-header regresseerde in een recente deployment — een prestatieprobleem lang voordat het een storing wordt.
4xx Clientfouten: wiens schuld is het echt?
4xx-codes heten "clientfouten", maar dat label is misleidend voor monitoringdoeleinden — een plotselinge 4xx-piek is heel vaak jouw schuld. Een piek in 400 Bad Request vlak na een deployment betekent meestal dat een validatieregel is veranderd en bestaande clients er nu niet meer aan voldoen. 401 Unauthorized en 403 Forbidden zijn geïsoleerd verwacht (foute inloggegevens, verlopen tokens), maar een plotselinge sitebrede piek wijst op een kapotte auth-service of een verkeerd geconfigureerde gateway — niet op duizenden gebruikers die plots hun wachtwoord verkeerd typen.
404 Not Found verdient een baseline in plaats van een harde alert — het internet zit vol scanners en verouderde links. Wat telt is de verandering: als een specifiek endpoint dat 200 teruggaf plots 404 gaat geven, is dat een routeringsregressie, geen achtergrondruis. 429 Too Many Requests is de ene 4xx waarop je bij kritieke integraties bijna altijd moet alerteren — het betekent dat legitiem verkeer wordt afgeknepen, en als het aanhoudt raakt het precies de gebruikers waar je het meest om geeft.
5xx Serverfouten: de codes die je wakker moeten maken
5xx-codes zijn ondubbelzinnig: iets aan jouw kant van de lijn faalde. 500 Internal Server Error is de generieke verzamelcode — nuttig als rookmelder, maar duik altijd in de logs om de echte exception erachter te vinden. 502 Bad Gateway betekent dat je load balancer of reverse proxy geen geldige respons kreeg van een upstream-service — controleer de gezondheid van wat er achter je gateway zit, niet de gateway zelf. 503 Service Unavailable geeft meestal aan dat de service bewust verkeer weigert (overbelastingsbescherming, onderhoudsmodus of een geactiveerde circuit breaker), terwijl 504 Gateway Timeout betekent dat de upstream er simpelweg te lang over deed om te antwoorden.
Deze drie — 502, 503, 504 — worden vaak verward maar wijzen naar verschillende lagen van je stack, en alerteren op "5xx" als één emmer verspilt de diagnostische waarde die de specifieke code al gratis geeft. Een monitoringopstelling die de exacte code toont, niet alleen "5xx gedetecteerd", verkort de triage van minuten naar seconden.
