Not Implemented
ActiveHTTP 501 Not Implemented indicates the server does not support the functionality required to fulfill the request. Defined in RFC 9110 §15.6.2. Typically means the request method is not recognized or not implemented by the server at all. Different from 405 which targets a specific resource.
Description
The 501 Not Implemented status code indicates that the server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource. A 501 response is heuristically not cacheable unless otherwise indicated by the method definition or explicit cache controls.
The critical distinction between 501 and 405 is scope. 405 Method Not Allowed means the server recognizes the method but a specific resource refuses it — the Allow header tells you what works instead. 501 means the server has no idea what this method is, or has deliberately chosen not to implement it for any resource. There's nothing resource-specific about it — the entire server cannot handle this method.
In practice, 501 is rare with standard methods. Every HTTP server implements GET, POST, PUT, DELETE, HEAD, and OPTIONS. You encounter 501 when clients send extension methods like PATCH (on older servers), WebDAV methods (MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK), or completely custom methods (PURGE, LINK, UNLINK). It also appears when a required Transfer-Encoding or content coding is not supported by the server.
The server SHOULD return a 501 response when it receives a request method it does not recognize. This makes 501 effectively the server saying 'I don't know what you're asking me to do' rather than 'I know what you want but won't do it here.' Some reverse proxies and load balancers return 501 when the upstream hasn't implemented a particular feature or protocol extension they're expected to support.
From an operational perspective, 501 responses often indicate a client misconfiguration (talking to the wrong server), a version mismatch (expecting HTTP/2 features from an HTTP/1.1-only server), or an incomplete server implementation during development. Unlike 503 (temporarily unavailable), 501 implies a permanent limitation — retrying won't help unless the server is upgraded.
Examples
PATCH /api/users/42 HTTP/1.1
Host: legacy-api.example.com
Content-Type: application/json-patch+json
Authorization: Bearer token123
[{"op": "replace", "path": "/email", "value": "[email protected]"}]HTTP/1.1 501 Not Implemented
Content-Type: application/json
Content-Length: 142
{"error": "not_implemented", "message": "The PATCH method is not supported by this server. Use PUT for full resource replacement.", "supported_methods": ["GET", "POST", "PUT", "DELETE"]}MKCOL /remote.php/dav/files/user/new-folder HTTP/1.1
Host: files.example.com
Authorization: Basic dXNlcjpwYXNzHTTP/1.1 501 Not Implemented
Content-Type: text/plain
Content-Length: 89
The method MKCOL is not implemented by this server. WebDAV extensions are not available.PURGE /cache/images/hero.jpg HTTP/1.1
Host: cdn.example.com
X-Purge-Key: secret-key-123HTTP/1.1 501 Not Implemented
Content-Type: application/json
{"error": "not_implemented", "message": "The server does not recognize the PURGE method."}Edge Cases
- •501 means the SERVER doesn't implement the method at all — not that a specific resource rejects it. If only certain resources reject the method, use 405 with an Allow header instead.
- •Standard methods (GET, POST, PUT, DELETE, HEAD, OPTIONS) should never return 501 on a compliant server. If they do, the server is broken, not the client.
- •PATCH is the most common standard-ish method to trigger 501 because RFC 5789 defines it separately from RFC 9110, and older servers may not implement it.
- •Reverse proxies may return 501 when they can't handle a Transfer-Encoding value (e.g., chunked on an HTTP/1.0 proxy) — this is technically correct per RFC 9110.
- •Some CDNs return 501 for methods they don't proxy (like CONNECT or TRACE), even though the origin server might support them.
- •A 501 response should NOT include an Allow header — that's for 405. Including one on a 501 creates confusion about whether the issue is resource-level or server-level.
- •Load balancers may return 501 during deployment when the backend hasn't finished registering its route handlers — a transient version of a permanent error code.
When You'll See This
- →Sending PATCH to a legacy server that only implements GET/POST/PUT/DELETE
- →WebDAV client (MKCOL, PROPFIND, LOCK) connecting to a non-WebDAV server
- →Custom cache purge method (PURGE) sent to a server that doesn't support it
- →HTTP client using LINK/UNLINK methods against a modern REST API
- →Proxy server receiving a Transfer-Encoding it cannot process
- →CDN returning 501 for CONNECT or TRACE methods it doesn't proxy
- →API gateway that hasn't been configured to forward a particular method to the backend
Implementation References
| Language | Constant |
|---|---|
| Go | http.StatusNotImplemented |
| Rust | http::StatusCode::NOT_IMPLEMENTED |
| Python | http.HTTPStatus.NOT_IMPLEMENTED |
| Node.js | http.STATUS_CODES[501] |
| .NET | HttpStatusCode.NotImplemented |
| Java | HttpURLConnection.HTTP_NOT_IMPLEMENTED |
| PHP | Response::HTTP_NOT_IMPLEMENTED (Symfony) |
| Ruby | :not_implemented (Rack) |
History
Introduced in HTTP/1.1 (RFC 2068, 1997) alongside the full status code taxonomy. Gained relevance with WebDAV (RFC 2518, 1999) which added methods like MKCOL, PROPFIND, and LOCK that most standard servers don't implement. Carried forward unchanged into RFC 9110 (2022) as the canonical response for unrecognized request methods.
Related Status Codes
Related Headers
FAQ
What is the difference between 501 Not Implemented and 405 Method Not Allowed?
501 means the server doesn't recognize or support the method for ANY resource — the entire server cannot handle it. 405 means the server knows the method but a specific resource doesn't accept it, and includes an Allow header listing what does work. Think of it as: 501 = 'I don't speak that language' vs 405 = 'I speak it, but not here.'
Should I retry a request that received 501?
No. 501 indicates a permanent server limitation, not a transient failure. The server doesn't implement the method, so retrying the same request will always fail. Either switch to a method the server supports (e.g., PUT instead of PATCH), or talk to a different server that implements the required functionality.
When would a standard method like GET or POST return 501?
Virtually never on a compliant server. All HTTP/1.1+ servers must implement GET and HEAD at minimum. If you receive 501 for GET or POST, the server is either severely broken, you're hitting a stub/mock that hasn't been implemented yet, or a proxy is intercepting your request before it reaches the real server.