What does HTTP status 501 Not Implemented mean, and when is it the correct response for a server to send?
answer
- Server-wide capability gap, not this resource
- Classic case: unrecognised request method
- Cacheable by default — add no-store if temporary
- Not for business rules or plan limits
- Gateway that cannot perform the operation
basics
~20 s501 means the server does not support the functionality needed to fulfil the request at all — typically it does not recognise or implement the request method for any resource. It is about a missing capability, not a missing or wrong resource.
solid answer
~50 s501 Not Implemented says the server lacks the capability to fulfil the request — it does not recognise the method, or does not implement some required feature, for **any** resource, not just this one. The classic trigger is a request method the server has no implementation for at all, such as an exotic or unrecognised verb arriving at a plain HTTP server. Two details matter. First, it is server-wide: if a method is generally supported but not allowed on this particular resource, that is a different, resource-scoped answer, not 501. Second, 501 is cacheable by default under HTTP's rules unless you say otherwise, because "this server does not implement that" is expected to be stable; if it is really a temporary gap, add explicit cache directives or use a different code. In practice most APIs return 501 rarely — for an unshipped endpoint behind a feature flag, or from a gateway asked to do something it cannot proxy.
go deeper
Recall that 501 means the server does not implement the requested functionality, most often an unsupported request method, and that it is a server-side (5xx) code.
Draw the scope distinction — server-wide capability versus this resource — and know that 501 is cacheable by default.
Discuss real deployment consequences: placeholder 501s being cached at the CDN, gateways emitting it, and why 503 is the right code for transient dependency failure.
Frame it as contract hygiene — what your API promises about verb support, how unimplemented operations are surfaced during progressive rollout, and how cacheability defaults interact with that.
## Definition 501 Not Implemented means the server does not support the functionality required to fulfil the request. The canonical case is an unrecognised or unsupported **request method**: the server cannot act because it has no implementation of that verb whatsoever. The status is a statement about the server's capabilities, not about the state of a particular resource. ## The scope test The single most useful discriminator to have in your head is scope. - If the server **never** supports this method, for any target — 501. - If the server supports the method in general but the **target resource** does not permit it — that is a resource-scoped, client-side answer in the 4xx range, and it is a different topic entirely. So a server that implements GET, POST, PUT and DELETE but receives some unknown verb has a 501 situation. A server that implements DELETE broadly but exposes a read-only report endpoint does not — refusing there is about that resource, not about a missing capability. ## Caching behaviour HTTP defines a set of status codes that are cacheable by default, and 501 is on that list. The reasoning is that a capability gap is a durable property of the server: if it does not implement something now, it probably still will not in five minutes. That default has a practical consequence — if you use 501 as a placeholder for an endpoint that is coming next sprint, an intermediary cache may store it and keep serving the 501 after you ship the real implementation. Guard against that by sending explicit cache directives such as `Cache-Control: no-store` alongside it. ## Where 501 legitimately shows up - **Origin servers meeting an unknown method.** A framework or web server that dispatches on method and finds no handler for the verb at all. - **Gateways and proxies.** An intermediary asked to perform something it cannot — a method or extension it does not know how to forward or translate — may answer 501 rather than mangle the request. - **Deliberately unshipped functionality.** An API that publishes a route contract ahead of implementation may return 501 for the not-yet-built operation, ideally with `no-store` and a body explaining the state. ## Where candidates misuse it The most common mistake is reaching for 501 as a generic "we do not do that" code for business rules — an unsupported currency, an unsupported file type, a feature the customer's plan does not include. Those are properties of the request or of authorization, not of the server's implemented capabilities, and they belong in the 4xx range. The second mistake is using 501 for a temporarily broken feature, where a dependency is down; that is a temporary unavailability and 503 communicates it far better, including the ability to attach a retry hint. ## Relationship to method discovery Because 501 is about implemented methods, it sits near the machinery a server uses to advertise what it can do. A server answering 501 has no obligation to tell the client what it *does* implement; that advertising happens through other mechanisms in the protocol. In an API, do not expect clients to discover your verb support by probing for 501 — document the contract instead. ## Practical summary Treat 501 as rare and precise. Ask: is the client asking for something this server fundamentally cannot do, for anyone, anywhere? If yes, 501 is honest. If the answer is "we can, but not here" or "we can, but not right now", another code carries the meaning better.
- Why can returning 501 for an endpoint you plan to ship next month cause a problem?501 is cacheable by default, because HTTP assumes a missing capability is a durable property of the server. An intermediary cache or CDN may store the 501 and keep serving it to clients after you deploy the real implementation. If you use 501 as a placeholder, send explicit cache directives such as Cache-Control: no-store so nothing retains it.
- A dependency your feature relies on is down, so the feature cannot run. Is 501 the right code?No. 501 asserts the server has no implementation of the functionality at all, which is a permanent-sounding claim. A dependency outage is temporary unavailability, which is what 503 Service Unavailable describes, and 503 lets you attach a Retry-After hint. Using 501 here misleads clients and caches into treating a transient outage as a capability gap.
saying these in an interview costs you the question
- Using 501 for a method that is supported elsewhere but not allowed on this specific resource.
- Treating 501 as a general-purpose "unsupported option" code for business rules such as an unsupported currency or file type.
- Returning 501 for a temporarily broken feature instead of 503.
- Not realising 501 is cacheable by default and leaving placeholders cacheable.
- Assuming 501 is a client error because it sounds like the client asked for something wrong.