Status Codes

If you've ever consumed and/or created any sort of RESTful service, then you will have encountered various HTTP status codes in the response. Many developers do not have very good knowledge in such a foundational area, probably because there are just way too many that it becomes overwhelming at times. The official standards and list of HTTP codes can be found here (Standard - IETF RFC 7231 and Additional - IETF RFC 6585).

In this section we are going to go over what the big categories of HTTP status codes are. More importantly, we will cover only the most important and commonly used status codes and some guidelines on when/how to use them appropriately.

Brief Overview of the Categories

There are essentially 5 categories of HTTP status codes, and each can be summarized in one sentence.

• 1xx (Informational): The request was received, continue processing.

• 2xx (Successful): The request was successfully received, understood, and accepted.

• 3xx (Redirection): Further action needs to be taken in order to complete the request.

• 4xx (Client Error): The request from the client cannot be fulfilled due to malformed inputs.

• 5xx (Server Error): The server failed to fulfill a valid request from the client.

For the full list, head over to https://developer.mozilla.org/en-US/docs/Web/HTTP/Status.

100 – 199 (Informational) Guidelines

In the context of creating APIs, this can be ignored. To learn more, head over to https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#information_responses.

200 - 299 (Successful) Guidelines

The 200s status codes generally tell the client that the request was successful. This is usually used with either a POST or PUT request, or any time a user is creating something. There are a ton of rarely used 200 status codes, below is a list of the most used ones.

Code	Name	Guidelines
200	OK	Should be used to indicate generic success. Unlike the 204 status code, a 200 response should include a response body. Should not be used to communicate any types of errors in the response body.
201	Created	Must be used to indicate successful resource creation; usually via a POST request.
204	No Content	Should be used when the response body is intentionally kept empty. If you are using any of the other 200 status codes besides this one, it is good to always provide some sort of non-empty body in order to avoid confusion. The 204 status code is useful when using it with a DELETE request, since when you delete something there is nothing to return.

300 - 399 (Redirection) Guidelines

The 300s are not particularly important in the context of creating RESTful APIs, because their main importance are in the field of SEO. However, below are a couple that are quite important to know and understand.

Code	Name	Guidelines
301	Moved Permanently	Should be used to relocate resources. The 301 status code indicates that the current URI has been significantly redesigned and a new permanent URI has been assigned to the client’s requested resource. The REST API should specify the new URI in the response’s Location header.
304	Not Modified	Should be used to cache information. This is commonly used to cache GET requests, if a REST call is made from the client in which it yields the same unmodified result every time, then you should use the 304 status code.

400 - 499 (Client error) Guidelines

The 400s are probably the most important out of all the other categories. These are the ones that the client calling your API has to interact with. Imagine these status codes as a way of providing form validation and signaling to the client what is right or wrong. The 400 category contains the most out of any of the other categories, there are over 30 different 400 status codes. Below are the most commonly used ones that you must know.

Code	Name	Guidelines
400	Bad Request	May be used to indicate a generic failure from the client. 400 is the default generic client side error status, used when no other 4xx error code is appropriate. Be as specific as possible by using the other 4xx error codes and don't overuse this.
401	Unauthorized	Must be used when there is a problem with the client’s credentials. A 401 status code indicates that the client tried to access a resource without proper authentication.
403	Forbidden	Should be used to forbid access regardless of authorization state. A 403 status code indicates that the client’s request lacks sufficient permissions; this is different from a 401 status code because with a 403 status code, the user can provide correct credentials but not have the necessary access levels.
404	Not Found	Must be used when a client’s URI cannot be mapped to a resource. The 404 status code is the most common, it is a catch-all-exception that gets defaulted when a URI cannot be found. Use the 404 status code for dynamic URIs with entity Ids (ex. https://website.com/people/john).
409	Conflict	Should be used to indicate a violation of resource state. The 409 status code can be used in instances to indicate to the client that perhaps a user with the same email cannot be created more than once, or an update to a resource is not possible due to the application's business logic.
422	Unprocessable Entity	Should be used indicate malformed inputs. This is usual most commonly used when there are form validation errors.

500 - 599 (Server error) Guidelines

Finally, the 500 status codes. Most of the time, a general 500 error is enough to indicate to the client what is going on. I am not going to stress too much about the 500 errors, it is beyond the scope of this book. You can read more about it on MDN: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses.

Code	Name	Guidelines
500	Internal Server Error	Should be used to indicate to the client that they did nothing wrong, but rather there was an error on the server.