Understanding HTTP 501 Not Implemented: Unknown Methods, 501 vs 405, and Why It Isn't a Coming-Soon Page
501 Not Implemented sounds like the status code for an unfinished feature, and the name practically asks you to return it from an endpoint you haven't written yet. That reading is wrong. 501 is about the server, not a resource: the server doesn't recognise the request method and can't support it on any URL. Its closest neighbour is 405 Method Not Allowed, which means the method is fine in general but not allowed on this resource. This post covers where the line between them sits, why 501 makes a poor "coming soon" stub, why caches may keep it, and what Node, Express, Next.js and NGINX really send for a method they don't know (rarely a 501).
What Is a 501?
A 501 means the server lacks the functionality the request needs, most commonly because it doesn't implement the request method at all.
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 cacheable; i.e., unless otherwise indicated by the method definition or explicit cache controls (see Section 4.2.2 of [CACHING]). — RFC 9110, Section 15.6.2
In plain English: "I don't speak that verb, anywhere." A server that only implements GET, HEAD and POST answers a PROPFIND with a 501 whichever URL it targets. The second paragraph is the one people skip: without explicit cache headers, a 501 can be cached.
501 vs 405: The Server vs This Resource
RFC 9110 draws the line in its methods overview:
An origin server that receives a request method that is unrecognized or not implemented SHOULD respond with the 501 (Not Implemented) status code. An origin server that receives a request method that is recognized and implemented, but not allowed for the target resource, SHOULD respond with the 405 (Method Not Allowed) status code. — RFC 9110, Section 9.1
The question is whether the method works anywhere on the server:
- 501 = "I don't do that." The method is unknown or unimplemented server-wide. A different URL won't help.
- 405 = "Not here." The server handles the method elsewhere, just not on this resource.
So DELETE /users on an API that supports DELETE /users/42 is a 405. PROPFIND /users on a server with no WebDAV support is a 501. Strictly, DELETE on a server with no DELETE handler anywhere is a 501 too, though most servers send 405 or 404 instead.
The same section sets a floor on what "not implemented" can cover:
All general-purpose servers MUST support the methods GET and HEAD. All other methods are OPTIONAL. — RFC 9110, Section 9.1
A general-purpose server never answers GET or HEAD with 501. Every other method, POST included, is optional.
The two codes also differ in what they must carry. A 405 describes a resource, so it has to list what that resource accepts:
An origin server MUST generate an Allow header field in a 405 (Method Not Allowed) response and MAY do so in any other response. — RFC 9110, Section 10.2.1
A 501 describes the server, so no header is required. A 405 without Allow breaks a MUST; a 501 without it is fine. Our 405 Method Not Allowed post covers the Allow side in detail.
What Servers Actually Do With an Unknown Method
The spec recommends 501 for unknown methods. Here's what common stacks send by default, tested on Node 24, Express 5.2 and Next.js 16.4, and read from the current NGINX source. FOO is a made-up method, PROPFIND is a real WebDAV method nobody implemented here, and DELETE is a standard method the route doesn't handle:
| Stack | FOO /items | PROPFIND /items | DELETE /items (no handler) |
|---|---|---|---|
Node http server | 400, before your handler runs | Reaches your handler | Reaches your handler |
| Express 5 | 400 (from Node) | 404 | 404 |
| Next.js route handler | 400 (from Node) | 400 | 405, no Allow header |
| NGINX serving files | 405 | 405 | 405 |
NGINX with proxy_pass | Forwarded upstream | Forwarded upstream | Forwarded upstream |
None of them sends a 501 by default:
- Node's parser only accepts methods in
http.METHODS: the standard ones plus WebDAV,PURGE,QUERYand a few others. Anything else, including a lowercaseget(methods are case-sensitive), fails parsing. Node fires the server'sclientErrorevent, whose documented default is to close the socket with a 400, and your handler never runs. - Express takes its routing methods from that same list, so
PROPFINDgets through, then falls through to the default 404 like an unknown URL. Express does answerOPTIONSautomatically, with anAllowheader. - Next.js route handlers support seven methods:
GET,HEAD,OPTIONS,POST,PUT,PATCHandDELETE. One theroute.tsdoesn't export gets an empty 405 with noAllowheader, even though the automaticOPTIONSresponse lists the exported methods. Anything outside the seven,PROPFINDincluded, gets an empty 400. - NGINX accepts any method made of uppercase letters,
_and-, and answers anything else with 400. Serving files from disk, it answers everything exceptGETandHEADwith its own "405 Not Allowed" page, with noAllowheader. As a reverse proxy, it forwards the client's method untouched unless you setproxy_method.
Put the last two rows together and FOO passes through NGINX, then Node rejects it with a 400. One request crosses two servers and never gets the code the spec recommends. That's rarely a disaster, since 400, 404 and 405 all stop the request. But if you want 501, you add it yourself.
One well-known exception: Python's built-in http.server answers any method its handler has no do_ method for with 501 Unsupported method, DELETE and PROPFIND included. For a server that only implements GET and HEAD, that's exactly what the RFC asks for.
501 vs Related Codes
| Code | Meaning | Use when |
|---|---|---|
| 501 Not Implemented | The server doesn't support this method or feature at all | Unknown or unimplemented method, unknown transfer coding |
| 405 Method Not Allowed | The method works, just not on this resource | DELETE on a read-only resource; must send Allow |
| 400 Bad Request | The request is malformed | Syntax errors, including a method that isn't a valid token |
| 404 Not Found | Nothing exists at this URL | Unknown routes, and endpoints that haven't shipped yet |
| 500 Internal Server Error | The server failed unexpectedly | Bugs and unhandled exceptions |
| 503 Service Unavailable | Temporarily unable to handle the request | Maintenance, overload, a feature switched off for now (with Retry-After) |
| 505 HTTP Version Not Supported | The protocol version is the unsupported part | The server won't speak the client's HTTP version |
The heuristic: 501 is permanent and server-wide, 405 is per resource, and 503 is temporary. If a different URL could succeed, it isn't a 501. If your next deploy will fix it, it isn't a 501 either.
501 Is Not a "Coming Soon" Page
The common misuse looks like this: an API ships POST /v2/exports as a stub that returns 501 until the real handler lands. The name fits and the message seems honest, but it's the wrong code:
- The method isn't the unimplemented part. Your server handles
POSTeverywhere else. What's missing is one resource's behaviour, which is a 405 (or a 404 if the resource doesn't exist yet). - It's a 5xx. It tells clients, dashboards and alerting that the server failed. A popular stub inflates your server error rate for a feature that's working as designed.
- Retries can't help. A client that retries 5xx responses will retry a 501 that can never succeed.
- It can be cached, as the next section explains.
Pick by what's really going on instead:
- Not shipped yet: don't route it, so the client gets a 404.
- The resource exists but a method on it isn't ready: a 405 with an honest
Allowheader. - Built but switched off for now: a 503 with
Retry-After, which says "temporary" explicitly. Our 503 Service Unavailable post covers it.
501 Is Heuristically Cacheable
RFC 9110 names the status codes caches may store without explicit freshness information: 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414 and 501. 501 is the only 5xx on that list. RFC 9111, Section 4.2.2 lets a cache guess a lifetime for such a response, suggesting a fraction (10% is its example) of the time since Last-Modified.
That makes sense for real 501s: a method the server doesn't implement today won't appear in the next few minutes. And caches only store responses to methods they understand (RFC 9111, Section 3), so a 501 for PROPFIND is unlikely to be stored at all. Caching bites the misuse: a "coming soon" 501 on a GET that a spec-following cache may keep serving after the endpoint ships. If the answer could change, say so:
HTTP/1.1 501 Not Implemented
Cache-Control: no-storeThe Other Legitimate 501s
The HTTP/1.1 message syntax spec gives 501 two more jobs:
A server that receives a request message with a transfer coding it does not understand SHOULD respond with 501 (Not Implemented). — RFC 9112, Section 6.1
Section 3 adds that a server receiving "a method longer than any that it implements" SHOULD answer 501 rather than keep reading. NGINX follows the first rule: a Transfer-Encoding other than chunked gets a 501 and a closed connection. This is where you're most likely to meet a 501 you didn't write.
Common Causes
- An unknown or unimplemented method. A WebDAV client (
PROPFIND,MKCOL), a scanner sending made-up verbs, or aPUTagainst a minimal server like Python'shttp.server. This is the correct use. - An unknown
Transfer-Encoding. A client or proxy sends a transfer coding the server doesn't support. - A stub for an unfinished feature. The misuse above: a handler that returns 501 until someone writes the real code.
Returning 501 Correctly
The rule on every platform: check the method against what the whole server implements, before routing. Once routing has run, you're answering for one resource, and that's a 405 or a 404.
Express / Node.js
import express from "express";
const IMPLEMENTED = new Set(["GET", "HEAD", "OPTIONS", "POST", "PUT", "PATCH", "DELETE"]);
const app = express();
// Runs before any route, for every method Node's parser accepts
app.use((req, res, next) => {
if (!IMPLEMENTED.has(req.method)) {
return res.status(501).json({
error: "not_implemented",
message: `${req.method} is not supported by this server.`,
});
}
next();
});
// ...routes...
const server = app.listen(3000);
// Methods Node can't parse (FOO, lowercase get) never reach Express
server.on("clientError", (err, socket) => {
if (err.code === "ECONNRESET" || !socket.writable) {
socket.destroy();
return;
}
const status =
err.code === "HPE_INVALID_METHOD"
? "501 Not Implemented"
: err.code === "HPE_HEADER_OVERFLOW"
? "431 Request Header Fields Too Large"
: "400 Bad Request";
socket.end(`HTTP/1.1 ${status}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
});The middleware catches methods Node knows but you don't implement, like PROPFIND. The clientError listener catches methods Node can't parse. A listener replaces Node's default handling for every parse error and must close the socket itself, which is why it still maps the 400 and 431 cases. Skipping it is fine too: a 400 for gibberish methods is defensible.
Next.js App Router
A route handler can't send this 501, because PROPFIND gets a 400 before your code runs. proxy.ts (the Next.js 16 name for middleware) runs earlier:
// proxy.ts
import type { NextRequest } from "next/server";
const IMPLEMENTED = new Set(["GET", "HEAD", "OPTIONS", "POST", "PUT", "PATCH", "DELETE"]);
export const config = { matcher: "/api/:path*" };
export function proxy(request: NextRequest) {
if (!IMPLEMENTED.has(request.method)) {
return Response.json(
{ error: "not_implemented", message: `${request.method} is not supported by this server.` },
{ status: 501 },
);
}
}Methods Node's parser rejects still get Node's 400. For a standard method a route.ts doesn't export, Next's automatic 405 is the right code. It just lacks Allow, so export the method and return { status: 405, headers: { Allow: "GET, HEAD" } } yourself if you want it spec-complete.
NGINX
server {
listen 80;
# Methods this server implements anywhere; everything else is a 501
if ($request_method !~ ^(GET|HEAD|OPTIONS|POST|PUT|PATCH|DELETE)$) {
return 501;
}
location /api/ {
proxy_pass http://app;
}
}This stops unknown methods at the edge instead of forwarding them to an upstream that answers 400. Per-resource restrictions still belong in each location, returning 405 with Allow, as the 405 post shows.
REST API JSON body
HTTP/1.1 501 Not Implemented
Content-Type: application/json
Cache-Control: no-store
{
"error": "not_implemented",
"message": "PROPFIND is not supported by this server.",
"supportedMethods": ["GET", "HEAD", "OPTIONS", "POST", "PUT", "PATCH", "DELETE"]
}Listing the supported methods is optional but saves the client a trip to your docs.
501 and SEO
Crawlers use GET and HEAD, which every general-purpose server must support, so a crawler should never meet a genuine 501. If one does, it's a stub on a public page or an error handler mapping exceptions to the wrong code.
Google's documentation doesn't single out 501, but its rules for 5xx apply: server errors make Google's crawlers slow down, and URLs that keep returning one are eventually dropped from the index. A placeholder page that answers 501 tells Google your server is failing. Serve unfinished pages with a real 200, or don't link them until they're ready.
Common Pitfalls
- Using 501 for "this resource doesn't support that method." If the server handles the method anywhere, it's a 405 with an
Allowheader. - Using 501 as a "coming soon" stub. It reads as a server failure, invites pointless retries and can be cached. Use 404 until it ships, or 503 with
Retry-Afterwhile it's switched off. - Returning 501 for
GETorHEAD. General-purpose servers MUST support both. - Sending 501 without
Cache-Controlwhen the answer might change. Addno-store. - Checking inside a route handler. That can only speak for one resource, which makes it a 405. A real 501 is decided before routing.
- Leaving placeholder 501s in production. A handler that returns 501 "until we build it" is easy to forget. Search for them before launch.
Wrapping Up
501 is a statement about the whole server, not about one endpoint. The rules of thumb:
- 501 means the server doesn't implement this method (or transfer coding) for any resource
- 405 means the method works, just not here, and must carry
Allow; 501 needs no header GETandHEADare never a valid 501 on a general-purpose server- 501 is the only heuristically cacheable 5xx, so send
Cache-Control: no-storeif the answer could change - For unfinished endpoints, use 404 until they ship, or 503 while a feature is switched off
- Node, Express, Next.js and NGINX don't send 501 for unknown methods by default; check the method before routing if you want them to
For more, see our pages on 501 Not Implemented, 405 Method Not Allowed and 503 Service Unavailable. The per-resource side of this story is in our understanding 405 Method Not Allowed post, the rest of the 5xx family starts with understanding 500 errors, and you can compare 405 vs 501 side by side.