501 Not Implemented

The short version: Work out which layer answered by bypassing your CDN or proxy and sending the same request to the origin, since edge layers reject unusual methods before your application sees them. If the origin returns it too, the server genuinely does not implement that method or header, so change the request. Do not retry: unlike other 5xx codes, nothing about a 501 is transient.

Key takeaways

• 501 Not Implemented means the server does not support the functionality needed to fulfil the request. It is the one 5xx that describes a limitation rather than a failure.
• It differs from 405 by scope. A 405 says the method is not allowed on that URL; a 501 says the server does not implement it anywhere, for anything.
• Unusually for a 5xx, RFC 9110 makes 501 heuristically cacheable, because a server that does not implement something will not implement it a second later.
• Do not retry it. Despite the 5xx status, nothing about the situation is transient, so retry logic should treat it like a client error and change the request instead.
• A proxy, CDN, or gateway can return 501 for a method your application would have handled perfectly well, which is why bypassing the edge is the fastest way to locate it.

Error type

HTTP 5xx server error

Whose side

The server, but as a limitation rather than a fault

Fix difficulty

Moderate

Common cause

The server does not support the required functionality

What does 501 Not Implemented mean?

A 501 Not Implemented tells the client that the server does not support the functionality required to fulfil the request. RFC 9110 gives it a specific role: it is the appropriate response when the server does not recognise the request method and cannot support it for any resource. That word "any" is what separates it from the neighbouring 405, which is per-resource. A 405 means the method exists on this server but not on this URL, and the response must name the methods that are allowed. A 501 makes a broader statement about the server's capabilities.

It also behaves unlike its neighbours in the 5xx range. Most server errors describe something that went wrong and might not go wrong next time, which is why retrying with backoff is the standard response to a 500, 502, 503, or 504. A 501 describes a permanent limitation, so retrying achieves nothing. RFC 9110 goes further and makes 501 heuristically cacheable by default, on the same logic. That is worth remembering when you implement the missing feature, because intermediaries may keep serving the cached 501 after the capability exists.

501

HTTP status code

5xx

Server-side error class, though this one describes a limitation rather than a failure

Cacheable

The only common 5xx that RFC 9110 makes heuristically cacheable by default

How the 501 Not Implemented error appears

The wording changes depending on your browser, device, or server. Here is how this error commonly shows up:

example.com

501

Not Implemented

The server does not support the functionality required.

• 501 Not Implemented
• HTTP Error 501
• Error 501
• HTTP 501
• 501 Not Implemented nginx
• The server does not support the functionality required to fulfill the request

501 vs 405, 500 and 502

These are easy to conflate because all four come back when a request cannot be completed, but only one of them is about capability.

The 5xx codes, and which are worth retrying

They share a class but not a meaning, and the retry behaviour differs sharply between them.

What causes 501 Not Implemented?

• A request method the server does not implement at all, such as PATCH on an older stack or a WebDAV verb on a plain web server.
• A reverse proxy, CDN, or corporate gateway that only forwards methods it recognises, rejecting the request before your application sees it.
• A Transfer-Encoding the server does not support, which produces a 501 even for an otherwise ordinary request.
• An Expect header carrying a value the server does not recognise, most often 100-continue against a server that does not implement it.
• A stubbed handler: an endpoint present in routing whose implementation was generated as a placeholder and never written.
• A feature disabled at build or configuration time, so the code path exists but reports itself as unavailable.
• A misused status code, where the developer meant "not allowed on this resource" and should have returned 405 with an Allow header.

How to find the cause fast

1. Send the same request to the origin, bypassing any CDN or proxy. A 501 that vanishes was generated at the edge rather than by your application.
2. Try a simple GET to the same URL. If that succeeds, the method is the problem; if it also returns 501, look at headers and framing instead.
3. Check the response body and server logs for which component answered, since proxies and applications phrase the error differently.
4. Search the codebase for handlers that return 501 as a placeholder, which is a common pattern in generated or scaffolded code.

Terminal

curl -i -X PATCH https://example.com/api/items/7HTTP/1.1 501 Not Implemented# not "not allowed here": this server does not implement PATCH at all

How 501 Not Implemented looks from the outside

A 501 is a normal HTTP response, so the connection opens, TLS completes, and an answer comes back promptly. An up-or-down check will report the service healthy while a whole category of requests is being refused. It is also asymmetric in a way that hides it: the GET a basic monitor sends is usually implemented perfectly well, so nothing looks wrong from the outside while writes or unusual methods fail. Because a 501 can be cached, the effect can also outlive its cause, continuing to be served after the capability was added. Checking the methods that matter, and asserting the status you expect, is what surfaces both.

To confirm the exact code a URL returns, or to re-test several at once after a fix, run them through the free bulk URL status checker.

How to fix 501 Not Implemented

If you are calling an API

1. Use a method the server implements. If you need PATCH and it is unsupported, a PUT with the full representation is the usual alternative.
2. Do not retry the request unchanged. Unlike other 5xx codes, a 501 will not resolve itself, and retry loops only add load.
3. Check whether an intermediary is responsible by sending the request directly to the origin if you can reach it.
4. Look at your headers as well as your method, since an unsupported Transfer-Encoding or Expect value produces a 501 on an otherwise ordinary request.
5. Consult the API documentation for which methods the endpoint actually supports, rather than assuming a full REST verb set.

If you run the website

1. Return 405 with an Allow header when you mean "not allowed on this resource". Reserve 501 for functionality the server genuinely does not implement.
2. Check whether your proxy or CDN forwards the methods your API needs, since the edge commonly rejects PATCH and less usual verbs by default.
3. Implement the missing capability, or document clearly that it is unsupported so callers stop attempting it.
4. Remember the caching behaviour. After implementing a feature that previously returned 501, add explicit cache headers or expect intermediaries to keep serving the old response.
5. Audit generated or scaffolded code for placeholder handlers that still return 501 in production.
6. Log which component produced the response, so a 501 from the edge is distinguishable from one your application chose to return.

Still not fixed? Next steps

• Determine which layer answered. Bypass the CDN or reverse proxy and send the same request to the origin: a 501 that disappears was produced at the edge.
• Check whether the method is the problem at all. A 501 on an ordinary GET usually points at a header the server cannot handle, such as an unsupported Transfer-Encoding or Expect.
• Look for stubbed handlers. Frameworks and generated code often return 501 as a placeholder for an endpoint that was routed but never implemented.
• Remember the caching behaviour when you fix one. A 501 can be cached by intermediaries, so a corrected endpoint may keep returning the old answer until caches expire.
• If you meant to say "not allowed here", return 405 with an Allow header instead. Using 501 for a per-resource restriction misleads every client that reads it.

Code & configuration

Copy-paste starting points. Replace example.com and the paths with your own, and test changes on staging before production.

Find out which layer answered

# through the edge
curl -i -X PATCH https://example.com/api/items/7
# HTTP/1.1 501 Not Implemented

# straight to the origin
curl -i -X PATCH http://10.0.0.5:8080/api/items/7
# 200 OK  -> the proxy rejected it, not your application

Say "not here" with 405, not "not at all" with 501

// wrong: implies the server supports PATCH nowhere
http_response_code(501);

// right: this URL does not accept it, and here is what does
http_response_code(405);
header("Allow: GET, HEAD, PUT");

A cached 501 outlives the fix

# 501 is heuristically cacheable under RFC 9110, so send explicit
# headers if the answer is expected to change
Cache-Control: no-store

How to prevent 501 Not Implemented

A 501 answers quickly and cleanly, which is exactly why it hides: the server looks healthy, an ordinary GET still works, and only the requests that use the missing capability fail. Because the response can be cached by intermediaries, it can also keep being served after you have implemented the feature. Pulsetic checks your website and endpoints from multiple locations every 30 seconds and alerts you by email, SMS, voice call, Slack, Discord, Telegram, or webhook when a URL stops returning the status code you expect, so a category of requests failing silently becomes something you are told about.

Learn how Pulsetic's uptime monitoring detects this from the outside, across 15+ locations.

Sources and further reading

The specifications and vendor documentation this guide is written from, plus deeper reading on the parts it only summarises.

• MDN: 501 Not Implemented
• RFC 9110: HTTP Semantics (15.6.2 501 Not Implemented)
• MDN: HTTP request methods
• RFC 9110: HTTP Semantics