HTTP Status Code Explanations

I’m in the middle of building out two APIs right now. Responding to requests with proper headers is always important but it becomes a critical piece of functionality when your application is responding in a text-only or serialized format like XML or JSON. Maybe you can get away with sending a 200 Ok or 403 Forbidden status instead of a 401 Unauthorized when your response body is an HTML page explaining the error but when you’re dealing with API clients that’ll get them pissed off at you pretty quick. Response codes aren’t just for errors either. It’s important to use the best code for the type of reponse you want to send. I personally like to break down responses into three categories: success codes, redirects, and errors. I’m always having to look up HTTP response/status codes so I’m just going to store a list of them here. Some of the more common and useful ones will have nice full explanations. Enjoy.

1XX Informational

These are very rarely used but you never know when you might need them.

Code Definition
100 Continue This is useful when your request body is very large. The idea here is for the client to send the headers first, wait for the server’s response, then send the request body. If you have a multi-megabyte request body then it’s more efficient to know if the server is willing to accept it based on headers before you go ahead and send all that data over the wire.
101 Switching Protocols Client asks server to switch protocols and the server is saying “okay, I’ll do that”

2XX Success

200 OK is the one we all know. But there are others and maybe you’ll want to use them one day.

Code Definition
200 OK Standard response for any successful HTTP request.
201 Created A new resource was create on the server based on the request.
202 Accepted Request was accepted for processing but has not yet been completed. The request may or may not be acted on - you won’t know until it is actually processed.
203 Non-Authoritative Information The server processed the request and is sending back information that could be from a different source.
204 No Content Useful for DELETE requests. Basically means the request was successfully processed but there’s nothing to return.
205 Reset Content Same as 204 except the server requires the client to reset the document view.
206 Partial Content Indicates the server is only sending partial resource. This is usually because the client requested only a limited range of bytes, useful for resuming downloads or conserving bandwidth.

3XX Redirects

Now we’re getting into the more common respondes. 3XX and 4XX are, in my opinion, the mose useful responses besides 200 OK.

Code Definition
300 Multiple Choices Indicates the client has multiple choices for the same resource such as formats of the same file or different languages to choose from.
301 Moved Permanently Indicates that all future requests should be directed to the URL given in the response.
302 Found Technically this was supposed to be to indicate a temporary redirect.
304 Not Modified The resource requested hasn’t changed at all since the last request and no data is needed. Tells the client to just use the cached version since it’s the same.

This list of 3XX errors is not exhaustive. I left out the ones that will barely ever be used and/or are not supported by most clients and web application frameworks. Remember, just because the spec defines it one way doesn’t mean the industry hasn’t implemented it differently.

4XX Client Error

This is my favorite type of response besides 200 OK. Errors will always happen and making sure you let a client know what’s going on is good for security and good for your API clients.

Code Definition
400 Bad Request Request can’t be processed because the client didn’t send a request that could be understood by the server.
401 Unauthorized This is not the same as a 403! 401 Unauthorized means that the resource can be accessed only after the client authenticates.
402 Payment Required This really isn’t used the way it’s supposed to if at all. I personally will use it if an API client makes a request to a paid feature through a free account type.
403 Forbidden You should not use this to indicate a login failure. That’s what a 401 is for. 403 means that a client cannot access the resource requested regardless of whether they’re authenticated or not. So, to make it simple, 401 means the client needs to authenticate and 403 means that the client may be authenticated but still doesn’t have sufficient privileges to access a resource. This can be used in web apps where there are different levels of user permissions.
404 Not Found The resource was not found this time but it might come back. So instead of throwing a 301 or 302 you give a 404 to tell the client that if they try again in the future there’s a chance they’ll get what they came for.
405 Method Not Allowed Use in response to a request type that isn’t allowed for a specific resource. For example, if you allow GETs but have received a POST instead.
422 Unprocessable Entity The request was well formed but the server couldn’t respond because of semantic errors (usually something in your web app says “nope, I won’t allow this even though the request is okay”).
429 Too Many Requests Great for rate limiting.

5XX Server Error

For internal server errors.

Code Definition
500 Internal Server Error We all know this one. The request was fine but the application encountered an error. Super generic, you should provide more details if you can. Usually due to some error in your code and not the server software itself.
501 Not Implemented You shouldn’t have to use this. Clients should not be able to access features in development. However, if you have test features live that aren’t ready for prime time you can send this response to tell the client that the method they’re calling isn’t finished and will be in the future.
502 Bad Gateway This one always confuses me the most when I see it. It means the server was acting as a middleman between the client and another server and received a bad response from the upstream server. For example if your app is interfacing with an API, manipulating its data, and sending responses back.
503 Service Unavailable Send this when the server is overloaded and doesn’t have the resources to properly handle a request.
505 HTTP Version Not Supported We’re all using HTTP 1.1 these days still. Use this when a client is trying to talk to your server using a version of HTTP it doesn’t support. Usually handled for you by your server.
507 Insufficient Storage You better not run into this! We have Amazon Web Services and all sorts of other APIs to make sure you don’t have to physically store any long term data on your own server. I only store assets that my applications use on my own server. Anything a client may want to store goes to a trusted third party (S3 in my case) and is backed up. This status means your server ran out of storage space.
508 Loop Detected Your app found itself in an infinite loop and needs to quit the process. Better fix that in your code.

And that’s about all, folks. There are a bunch more but they’re either proprietary or ones you’ll never need to use. If you want a full list of HTTP status codes you can check out this Wikipedia page on the topic. Next week I’ll get into HTTP header fields and values.

Web development

« The Perks of Using Multiple Web Hosting Companies Installing Comodo Positive SSL Certs on Apache and OpenSSL »