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.
2xx codes means that there was some kind of success - but you can use other codes to communicate what actually succeeded.
I usually use this as a response to a
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.
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...
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.
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...
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
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
404 is used on requests where the URI does not exist - keep in mind that we have the
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...
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).
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.