A real web API needs machine parseable results (including HTTP error codes), stability, versioning, and a bunch of other things.

This is ground covered in Fielding’s dissertation. Mostly it needs content formats that are at once fine-grained and coarse-grained enough.

Versioning, if you refer to URL structures, is at best irrelevant, and easily leads to tight coupling. The whole and sole point of ReST is to be able to evolve both clients and servers independently from each other.

Stability, well that’s something human-oriented websites profit from no less than machine-oriented ones do.

A website designed for people is unlikely to have those (for good reasons).

I disagree that human-oriented websites do not require good status codes. Sure, they do not need them, but they will interoperate badly with the web at large. And as is true at all levels when it comes to the web: if you screw the pooch on interop, things will work badly but not not-at-all. It is very resilient. Is that a good reason to say “screw it”? Your call.

If you really are creating an API then you need to somehow make the responses machine-parseable and unambiguous, which may even require making up your own new HTTP error codes (or the less extreme version of embedding an additional status header with more details in the HTTP response).

… or returning them in some machine-readable way inside the body… remember the body? HTTP messages have those too, you know. :-)

Inventing new status codes should really be a measure of very last resort, because you are subsetting HTTP. New headers are slightly less bad, but still bad. Most people who do either really need neither… everyone just thinks their app or protocol is special.

If you're creating a web application for people what matters is what people will read; actual HTTP error codes are important only for their effects (if any) on caches, web crawlers, and so on if you care about any of those.

I am not sure how this is supposed to be an argument about anything. There is no contradiction nor any restriction from either part on the other. Both of those things are important.

Maybe the argument you are trying to make is that “interoperability is not the same as usability”? In which case the response is obviously “of course not”.

And if the argument you have been trying to make is something like “interoperability only matters for machine-oriented websites, whereas only usability matters for human-oriented websites”, well, when put that way, I think the answer to that is obvious.

Here is where web standards run into security engineering.

Do they? What I said (or at least meant! I may have failed to communicate) is that in terms of HTTP, all of 403, 404 and 501 would be equally valid choices in your scenario, so basing your choice among them on criteria outside HTTP itself and then picking any one of them is fine. The exception I made about 405 does not seem to conflict with you security concern either, since 405 is the most specific and informative status code among the ones you listed – so to the degree I understand your argument, you wouldn’t want to return that one anyway.

—Aristotle Pagaltzis

I want to mull over most of your comment and come up with a coherent reply, but on the issue of the error code example here's my thinking:

• 501 is inappropriate because it implies that this is a server failure instead of a client failure. (Although I think it's very common to return 501s here.)
• returning 404 for all DELETE requests is technically incorrect if some of the URLs exist (although it is justifiable under the '404 is a generic error' view).
• returning 405 does actually tell the client what it's doing wrong: it's making an unsupported request. This is technically true even if the URL doesn't exist, and is applicable to even, eg PUT requests (which don't necessarily require the target URL to exist in advance).

My view on error codes in response to request from nasty people is that you can do whatever you want, including what's most convenient or what you feel is most secure. But I still think you can decide to do something that 'makes sense' in your view if you want to.

I like 405 as a response partly because it's also applicable for more innocent requests like OPTIONS or TRACE.

501 is inappropriate because it implies that this is a server failure instead of a client failure. (Although I think it's very common to return 501s here.)

Why? :-) Because that is what 5xx is specified to mean in the spec? If I may remind you:

First off, I want to say that I fully agree with Aristotle's characterization that the real question to ask is what the practical effects of using any particular status code will be.

You said that. ;-)

So, OK. As the server’s author you don’t want to “accept the blame”… but I ask, what will clients do in response to 501?

This is not a rhetorical question, mind you – I really do not know. I think clients by and large are likely to behave in the way you’d like them to, namely, to cease trying (at least in short order – likely not immediately if the intent is malicious). But while I know how some of the other status codes get treated in some of the HTTP infrastructure, I don’t know much about 501. (Nor, for that matter, if shutting up the malevolent client is actually what you want.)

It would be useful to have some data on this.

—Aristotle Pagaltzis