Je stuurt een verzoek naar een server. De URL is geldig, je headers zijn netjes meegegeven, de payload klopt. Maar dan: response code 501 Not Implemented. Geen stacktrace, geen foutmelding in je app, alleen dat.
Wat gebeurt hier?
De 501 status code is zeldzaam, maar betekenisvol. Het geeft aan dat de server je verzoekmethode, bijvoorbeeld PUT, PATCH of DELETE, wel begrijpt, maar niet ondersteunt. Niet omdat het verzoek ongeldig is, maar omdat de server simpelweg niet weet wat-ie ermee moet.
Wat is http 501 precies?
De http 501 fout is onderdeel van de HTTP-specificatie en valt onder de 5xx-reeks: fouten aan de kant van de server. Maar in tegenstelling tot de generieke 500 status code, die gewoon zegt “er is iets misgegaan”, is 501 een stuk specifieker. Het zegt: deze methode is niet geïmplementeerd, en zal dus ook niet uitgevoerd worden.
Dat is wat ‘Not Implemented’ letterlijk betekent: de functionaliteit waar je om vraagt bestaat (nog) niet op de server. De server is niet stuk. Hij weigert gewoon iets te doen wat hij niet kan, of niet mag.
Wanneer zie je een 501 foutmelding?
In de praktijk duikt 501 http op in situaties waarin een client probeert een methode te gebruiken die de server niet ondersteunt. Een paar voorbeelden:
- Een frontend app probeert een PATCH-verzoek te sturen naar een endpoint dat alleen GET en POST accepteert.
- Een externe integratie verwacht bepaalde API-functionaliteit die aan serverzijde nooit is uitgerold.
- Een reverse proxy zoals NGINX of een WAF (Web Application Firewall) blokkeert specifieke methodes om veiligheidsredenen.
- Een verouderde serverstack die simpelweg geen support heeft voor bepaalde methodes.
In dat laatste geval zie je de fout ook wel terugkomen in oudere HTTP-implementaties, bijvoorbeeld bij embedded systemen of apparaten met beperkte ondersteuning voor moderne methodes.
Hoe herken je een 501 status code?
Als de fout via een frontend of browser zichtbaar is, zie je meestal iets als:
501 Not Implemented
The server does not support the functionality required to fulfill the request.
Bij het gebruik van tools zoals Postman, curl of Insomnia zie je de code direct in de response terug. En in je browserconsole, bij gebruik van bijvoorbeeld axios, kan het eruitzien als:
axioserror: request failed with status code 501
Bij crawling of technische audits, bijvoorbeeld met Screaming Frog, kan de 501 status code ook worden vastgelegd, vooral als je complexe route-structuren test of dynamische endpoints die methodes verwachten die niet universeel ondersteund zijn.
Hoe los je het op?
Een 501 status code oplossen betekent meestal: iets aan de serverkant aanpakken. De server snapt het verzoek, maar kan het niet afhandelen. De vraag is: waarom niet?
Een paar mogelijke oorzaken en richtingen om te onderzoeken:
- De backend ondersteunt de methode niet: Dit is het meest voorkomend. Voeg in je server of API-code ondersteuning toe voor de gevraagde methode (PUT, DELETE, etc.).
- Serverconfiguratie blokkeert methodes: Controleer instellingen in je .htaccess, nginx.conf of andere configuratiebestanden. Sommige servers blokkeren standaard methodes voor veiligheid.
- Proxy of WAF blokkeert methodes upstream: Reverse proxies, load balancers of firewalls kunnen PUT- of PATCH-verzoeken standaard weigeren. Kijk naar logging op netwerkniveau.
- Je client stuurt onbewust een unsupported method: In SPAs (Single Page Applications) of scripts kan een fout in routing of fetch-mechanisme ervoor zorgen dat een verkeerde methode wordt aangeroepen.
Gebruik eventueel een OPTIONS-verzoek naar het endpoint om te zien welke methodes daadwerkelijk ondersteund worden. Veel servers geven dan een Allow: header terug met de toegestane methodes.
Wat is het verschil met een 405?
Belangrijk onderscheid: bij een 405 Method Not Allowed zegt de server: “deze methode mag hier niet, maar ik ken ’m wel.”
Bij een 501 zegt de server: “deze methode ken ik niet of kan ik niet uitvoeren.” Subtiel, maar belangrijk, vooral bij debugging van API’s of routering.
Samenvattend
De 501 status code is niet zo alledaags als een 404 of 500, maar als je ermee te maken krijgt, is de boodschap duidelijk: de server begrijpt je vraag, maar voert hem niet uit, omdat hij simpelweg niet is ontworpen om dat te doen.
HTTP 501 is geen bug. Het is een ontbrekende feature.
Het is aan jou om te bepalen: hoort deze functionaliteit hier te bestaan? En zo ja, is het tijd om je backend uit te breiden, je configuratie te wijzigen of je frontend aan te passen?
Verwacht je wél support voor een bepaalde methode, en krijg je tóch een 501 http? Dan weet je in elk geval één ding zeker: de server praat wel terug, maar begrijpt je taal nog niet helemaal.
