The pragmatic issues around HTTP error codes mattering (or not)

August 3, 2013

When I posed the question of whether specific HTTP error codes actually mattered I put the question rather abstractly. But it's really a pragmatic question which I can put this way: how much effort is it worth putting into a web application that is used by people to get your HTTP error codes exactly and completely 'right'?

(I'm biased towards the server perspective because that's what I write, but if you write HTTP clients there's a mirror image question of how much sense it makes to write code that takes action based on fine distinctions in the response codes you get.)

I'll use DWiki (the ball of code behind my techblog) as an example. Broadly speaking DWiki can generate what are conceptually errors when people feed it all sorts of bad or mangled requests, when they ask for URLs that do not exist, when there are internal errors in page rendering (such as a bad template), when they are people we don't like, and when they don't have permission to access the URL. Today DWiki responds to almost all of these situations with either a 403 or a 404 status code, and some permission failures don't generate errors at all (instead you get a page with a message about it). Usually (but not always) DWiki generates 404 errors if the problem is something that could plausibly happen innocently and 403 errors otherwise.

(It would be nice to generate 403 errors for all permission denied situations but DWiki's architecture makes it quite hard for reasons that don't fit in the margins of this entry.)

Could DWiki do 'better', whatever that means? Perhaps. It could use error codes 400, 405, and maybe 505 in some situations, but these are all around the edges. Some uncommon issues should perhaps produce some 5xx error instead of a 404 because they are really a server-side problem with the page.

(DWiki also punts completely on a lot of semi-impossible situations. For example it assumes that either all clients can handle any format it wants to return or that the real web server will worry about checking for this and generating 406 errors when appropriate.)

I could go through every error generation in DWiki along with the list of HTTP status codes and try to match up each error with the closest match (which is often not very close; there are very few HTTP codes for relatively generic errors). But it very much appears to me that this would be both a lot of work for very little gain and also quite subjective (in that what I think is the right error code for a situation might not match up with what someone else expects).

Note again that this is for typical web apps and websites that are used by people instead of web APIs that are used by programs. Web APIs need to have as much thought put into error codes as any API needs into its error responses. But again, the best way to communicate most errors to API clients may not be through the very limited channel of HTTP error codes.

Sidebar: the subjectivity of HTTP error codes

Here are three examples of what I mean by subjectivity in HTTP error code choice.

  • A client requests a non-directory page but puts a '/' on the end of the URL (eg '/page/' instead of '/page'). Is this 400, 404, ignored (with the plain page being served), produces a redirection to the slashless version, or something else?

  • The server validates pages in some way before serving them to clients and a requested page exists but fails to validate. Is this 500, 503, 404, or something else?

    (Note that 404 is basically the generic error response and is documented as such in the HTTP/1.1 RFC.)

  • A client does a DELETE for a URL that doesn't exist and your web app doesn't support DELETE; in fact it only does plain old HEAD, GET, and maybe POST. Bearing in mind that this is extremely unlikely to be just an innocent mistake, is this 405, 501, 404, 403, or something else?

If you poll a bunch of web developers I think you will get a bunch of different answers for all of these.

Written on 03 August 2013.
« I'm giving up on a custom laptop environment for Fedora 19
The paucity of generally useful HTTP error codes »

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

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