Selecting the right HTTP response code

Published on 2016-07-12

The HTTP protocol have a lot of different response codes. Using the proper ones can really help you and your users. Communicating through the response codes can really help - especially when something goes wrong.

The Wikipedia page for the HTTP status codes has a complete list of codes - I will go over concrete use for some of these - but you should check out the complete list to get the full picture.

Here is a classic example of a HTTP response:

HTTP/1.1 200 OK
Date: Wed, 1 Jun 2016 16:19:00 GMT
Last-Modified: Sun, 1 May 2016 12:00:00 GMT
Content-Type: text/html
Connection: Closed

As you see the very first line is contain the response code - in this case 200 - this is the all clear signal - but things go wrong sometimes - and even if they don't - there are various options.

Success but...

The 2xx codes means that there was some kind of success - but you can use other codes to communicate what actually succeeded.

201 Created

I usually use this as a response to a POST or PUT request that creates something on the server. It is an effective way to tell in the HTTP that a resource was actually created and that everything went well.

202 Accepted

This code may seem very strange - accepted is a thing you can use if a request starts something bigger - an example of this can be an upload that starts a background processing of the uploaded data eg.

Check our this other thing...

The 3xx codes is generally thought of as redirects to find the actual content somewhere else.

301 Moved permanently

This let's you signal that the thing being requested is no longer found at this URI but all references (bookmarks, requests etc.) should instead be updated to a new location.

302, 303 and 308

The Wikipedia article mention some implementation details concerning these codes. You use these to signal that the resources is in another location. The 303 specify that the resource is at the new location but the following request should be a GET request no matter what type the original request was whereas 308 specify that the following request should be the same type.

Conflicting implementations of 302 suggest that you shouldn't use it.

These codes also specify that all references should be updated.

307 Temporary redirect

Where the previous redirects specify that pointers bookmarks etc. to the resource should be updated this response code indicate that this redirect is actually temporary and that the resource will be at the URI initially requested at some point again.

304 Not modified

This is a very useful response code. If the client have previously requested the resource it can include a If-Modified-Since portion in the request. That way the server can check if the resource has changed since that time and ommit the body if the response while returning the 304 code - that way processing power and precious bandwidth is saved.

You made an error...

The 4xx codes indicate that there was an error and it was caused by something the requester did (or didn't) do. The 4xx group holds a lot of different codes - here is some of the most important ones.

400 Bad request

This indicates to the requester that the request sent was somehow malformed. Maybe it had some invalid content eg.

401 Unauthorized and 403 Forbidden

These codes are used when resources are requested but the client doesn't have access to them and/or the client are using wrong credentials.

406 Not acceptable

This maingly regards the Accept header. If this is used to indicate the request content type and/or the expected respons content type the server can send this code back to signal that the specific content type is not supported (for this request).

404 Not found and 410 Gone

The 404 is used on requests where the URI does not exist - keep in mind that we have the 302, 303 and 308 if we know that the resource have been moved - the 404 is for situations where the server has no idea what the client is actually requesting. The 410 can be used when the resource is not there - it haven't been moved to another location but the server knows it have been there - it's simply gone.

429 Too many requests

For situations regarding load balancing eg. the 429 code can be used to indicate to the client that it have been sending too many requests and/or the server is currently at capacity overall.

Sorry, something went wrong...

The 5xx codes is reserved for situations where the server encounter some error internally - this can be while fetching, preparing, processing etc. - errors where the server is responsible and the client can't really do anything about it but wait.

500 Internal server error

This is the generic signal the server can send to the client - something went wrong, it's not you, it's me. This is probably the most used code in the 5xx series - the rest is very specific and ofted way too specific for the various errors the server can encounter.

501 Not implemented

A speciel code that can be used if the request have not yet been implemented but the server somehow knows that this is going to happen in the future.

502 Bad gateway and 504 Gateway timeout

If the server is acting as gateway or proxy to other resources. If this link fails somehow - either by general inavailability and/or request timeout these codes can be used to describe the situation properly.

503 Service unavailable

This can be used to indicate a temporary state where the server is not able to respond properly to requests. This can be due to maintainace and/or high load (where 429 might be a better response depending on the situation).

Conclusion

There are many repsonse codes in the HTTP specifications and here we have gone though the most used. You should check out the complete list to at least be aware of the rest if you are doing any kind of implementation.

Furthermore you are encouraged to use the most proper response code to describe the actual situation instead of falling back on the more generic codes.