Is HTTP 501 appropriate for an unimplemented API?

Question

Is an HTTP 501 error appropriate for functionality which the server plans to support, but does not currently, such as a particular case of an API? For instance, if I was designing a webmail app and I couldn't yet delete emails with attachments, would it be appropriate to give 501 if I got a DELETE request on an email with an attachment?

The RFC says that it should be used for an unknown method (e.g. a PARTY request), but it's not clear whether it should be used for other functionality as well.

Roughspoken

405/not allowed, or 406/not acceptable? – Seychelles

501 won't be expected by clients. i agree 4xx feels wrong. 503 might be a good option. "temporary server error". implies the client should try again later, which is the desired action you'd like the client to take, right? – Bantling

@Marc B 406(Not Acceptable) is about content negotiation, specifically that the server cannot support your Accept request header. 405(Not Allowed) has other complications that do not seem appropriate. I tend to agree with others that this needs to be a 500 series response. – Orren

no, unless you are writing your own HTTP server and some parts are not implemented yet. your case seems to be 404 (=API endpoint not found) and/or 405 (some HTTP method not handled yet). – Mercurate

Answer 1

appropriate

No:

6.6.2. 501 Not Implemented

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.

Use 405:

6.5.5. 405 Method Not Allowed

The 405 (Method Not Allowed) status code indicates that the method received in the request-line is known by the origin server but not supported by the target resource. The origin server MUST generate an Allow header field in a 405 response containing a list of the target resource's currently supported methods.

Ondrej

What if the method is only partially supported for that resource? Say, a complex POST routine, one part of which is unimplemented. The server can process any request that doesn't need that one part, but must give back an error if it does. Additionally, I was aware of that sentence you quoted about 501, but it's not explicit that that is the only valid use case for 501. – Roughspoken

I don't really like the "Which HTTP verb or status code to use for arbitrary situation X" questions. Just return a 400 and include a detailed report in JSON. – Ondrej

"You should not send that", i.e. a client error, warrants a 4xx. "I would like to process that, but don't know how (or an error occurred)", i.e. a server error, warrants a 5xx. – Ondrej

@Ondrej The advantage of being deliberate and consistent with the HTTP verb is then clients can respond reasonably to the response in a uniform way across different types of requests, without having to do additional operation-specific parsing of the response body in response to a more generic error code. – Indult

"This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource" specifies one situation in which it's appropriate; it doesn't claim to be inclusive of all situations where it might be appropriate. So it's unclear that this is the only intended or valid use of this error code. From that standpoint, "The server does not support the functionality required to fulfill the request" is the important part, and the second part is an example of where it's usually used. – Indult

@M.Justin no, you can't just pick and choose the verbiage that suits your scenario, because then you'll have to explain to your consumers why you deviate from the RFCs. – Ondrej

I am not downvoting regularily, but I had to, this time. 405 is way more inappropriate response. It's not a client error, so unless you don't want to disclose for some reason that you are not quite finished the implementation, you shouldn't retrun 405. I agree furthermore with @M.Justin that the wording of the 501 example is not signaled as exhaustive. The 500 section starts with: "The 5xx (Server Error) class of status code indicates that the server is aware that it has erred or is incapable of performing the requested method." which is precisely the situation described. – Exsiccate

405 on the other hand is a client error, signaling the exact resource in question is not MEANT to be used with the method tried by the client. Read: the client is in error, as he read the API spec wrong... Your API spec COULD change however in the future, so although the response is cacheable, different behaviour can be requested by response headers.... – Exsiccate

@KrisztiánSzegi it is a client error to send a DELETE request to an URL that doesn't support that method. Go read rfc-editor.org/rfc/rfc9110.html. – Ondrej

@KrisztiánSzegi all relevant parts are bolded in my answer. If the method does not implement the request method for any resource (i.e. it cannot handle DELETE on any URL), then you return a 501. Otherwise, return a 405. – Ondrej

I downvoted because I thought the answer was clear, especially reading 501's description in isolation. But reading 405's description adds a significant amount of ambiguity here. I don't feel like these descriptions are an improvement over RFC 2616, but I guess we'll have to wait for another RFC again. – Denysedenzil

Answer 2

From https://www.rfc-editor.org/rfc/rfc7231#section-4.1 :

When a request method is received that is unrecognized or not implemented by an origin server, the origin server SHOULD respond with the 501 (Not Implemented) status code.

When a request method is received that is known by an origin server but not allowed for the target resource, the origin server SHOULD respond with the 405 (Method Not Allowed) status code.

Nuclear