The paucity of generally useful HTTP error codes

August 3, 2013

One of the things that I didn't appreciate until I really looked at HTTP error codes is how few generally useful ones there are. To start with, we can divide HTTP error codes into two categories: specific technical failings and general errors. Specific technical failings are things like an Accept: header that the server can't satisfy. There's a bunch of 4xx errors for these cases (and a few 5xx errors), but they aren't useful in general since you're only supposed to generate them in specific technical circumstances.

Once you get into the officially specified general errors, though, there simply aren't that many: 403 Forbidden, 404 Not Found, 410 Gone, 429 Too Many Requests, and maybe 451 Unavailable For Legal Reasons (if you accept Internet drafts) and 400 Bad Request (if you stretch it). On the server error side, 500 Internal Error and 501 Not Implemented are basically it. Of the 4xx errors, only 403 and 404 are really general.

(It's striking how many unofficial HTTP error codes there are in the Wikipedia list. Apparently a lot of people have found the current set inadequate.)

This limited set of error responses means that a web application can't really tell clients very much about what went wrong using error codes alone (at least officially assigned ones). Consider, for instance, a web application that both has access-restricted content and blocks certain clients from some or all content. HTTP error codes alone provide no real way to distinguish between 'you can't have this content because you aren't properly authenticated' and 'you can't have this content because I think you're a robot and robots shouldn't be asking for this' (especially if the web app also has rate limiting and so uses 429).

This has wound up tied into my feeling that specific HTTP errors may not matter that much. If the available HTTP error codes are too limited to really communicate what you mean to the client, your choice of what specific error code you use from the limited general-use set is not necessarily very important.

Sidebar: technical failings versus general errors

I've realized that I draw a big, personal distinction between these two that doesn't necessarily exist. I consider technical failings to be the job of the web server (and the framework if any) to worry about and I basically ignore them when writing an application. The errors I care about are general errors.

Thus I need to clarify and effectively walk back some stuff I said when I asked whether specific HTTP error codes mattered. Getting the error code right for specific technical failings does matter (at least in theory). I was intending to focus on general, application level errors but both didn't make that clear and didn't appreciate just how many 4xx errors there are for technical failings until I'd looked at a list.

Comments on this page:

From at 2013-08-04 03:52:46:

I wonder how often the application just doesn't know enough about what's wrong (ie, some uncaptured fatal error) and thus can't send back anything more descriptive than a 5xx.

From at 2013-08-04 19:03:50:

Why is that surprising? You have a very obvious place to put a more detailed error response: the entity body! If you want to be machine- readable and specific, mint a format and MIME type that describes your specific error.

The status code OTOH is vitally important to HTTP-level infrastructure like intermediaries and middlewares like load balances, request routers and the like which by their nature do not look inside the content, and have to rely on the header information to decide what to do with the request. So you want codes to be fine-grained enough that such infrastructure has specific responses, but also coarse-grained enough that they map to such generic infrastructure.

Obviously that means that status codes that refer to specific protocol-level situations will be detailed, while the ones available to signal application-specific situations are going to end up as vague and broad categories.

Aristotle Pagaltzis

Written on 03 August 2013.
« The pragmatic issues around HTTP error codes mattering (or not)
What's changed in Unix networking in the last decade or so »

Page tools: View Source, View Normal, Add Comment.
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Sat Aug 3 23:34:51 2013
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.