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.
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.
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.
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.
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.
Last updated