HTTP Status Codes
Since the start of the internet servers have needed to communicate with clients. In today's internet clients are more commonly referred to as phones, computers or tablets. This communication became standardized with the HTTP protocol to include things such as response body and response header.
The response body holds the data that the client requested from the server. This might be the content of a webpage (aka HTML) or some data a client requested in the form of XML or JSON.
The response header is the server's way of adding meta-data to the response body. The header contains key-value data that the client can use to interpret the body. One of these pieces of information is the Status Code, which is a standard header of the HTTP Protocol.
What is a Status Code?
A status code is a 3-digit number provided by the web server in response to a client’s request. The first digit of the status code identifies the class of the response (Informational, Success, Redirection, Client Error or Server Error). The remaining two digits narrow in on the specific response type.
Why Should I Use Them?
This standardization of status codes has made HTTP and more specifically REST communication easier to implement across clients and servers. Instead of having to learn how a server will communicate a client request’s success or failure, a client can assume that any 201 sent from the server is the successful creation of a record. Whereas a 401 tell the client the request did not pass authorization by the server. Let’s explore each status code by class.
Using Status Codes in a REST API
HTTP has defined many different status codes each serving a specific purpose. The intent of this blog is not to go into detail on every one, rather to discuss the proper implementation of the most common codes used in a REST API. For a full list of status codes, we suggest checking out the rfc specification.
1xx - Informational
This class of status codes is for informational purposes only. A client must be able to receive a 1xx status code prior to receiving their expected response, however they can generally be ignored. Status codes of this class are typically not utilized in a REST API.
2xx - Success
This class of status codes indicates the client’s request was received, understood and processed by the server.
200 – OK
The request succeeded.
Example: a user search via a GET request or a PUT request that updates a user.
Note: This status code should only be used if no other 2xx code applies.
201 – Created
The request has successfully created one or more resources on the server.
Example: a POST request that adds a new user to the server’s database.
202 – Accepted
The request has been successfully received by the server however the processing of the request is not complete.
Example: an operation that sends a batch of emails overnight. In this example the server would return a 202 letting the requester know the request has begun processing and the client can move on. In this example the server would return a 202 prior to processing so the client could move on while the emails queue for sending.
Note: This status code does not guarantee the successful processing of the request. It is possible for the processing to fail. As a best practice, the response body of the 202 should provide information for the client to query the processing status.
204 – No Content
The request succeeded and no data is returned in the response body.
Example: a POST operation that clears a server’s cache.
Note: This status code should not be used when a different 2xx status could provide more information to the client such as a 201 (created) or 202 (accepted).
3xx – Redirection
This class of status code indicates further action needs to be taken in order to complete the request. Status codes of this class are typically not utilized in a REST API.
4xx – Client Error
This class of status code indicates the server is unable to process the request due to an issue with request itself. Responses with this status code require the client to act on in order to successfully process.
400 – Bad Request
The request was refused by the server due to a business rule or malformed syntax. The client must change the request before resending.
Example: a POST operation that creates data is missing a required property. In this example the 400 should return details on exactly what property is missing data.
401 – Unauthorized
The request did not contain the proper authorization information necessary to fulfil the request.
Example: a user accesses a resource with invalid credentials.
Note: A request that pass authentication but lacks permission would be better served with a forbidden status code.
403 – Forbidden
The request contains valid authorization information but the server refuses to process the request because the requesting client is not authorized to access the specific resource.
Example: a user requests data from an endpoint that is only accessible by administrators.
Note: A request with authorization information that is invalid, missing or malformed would be better served with an unauthorized status code.
404 – Not Found
The requested resource was not found; however, it may be available in the future. Subsequent requests by the client are permissible.
Example: a client requests a resource by id, however no resource is found.
Note: a GET endpoint should only return a 404 if the client expects a result. For example, an endpoint that allows a client to search for resources should always return a 200 status code regardless of the search results, however, an endpoint that locates a specific resource by id would return a 404 if the specific resource did not exist.
405 - Method Not Allowed
The request uses an HTTP verb that is not supported by the server.
Example: a client performs a PATCH request however the server does not support the PATCH verb.
429 - Too Many Requests
The client has sent too many requests based on rate limiting conditions established by the server. The response should include details explaining why the request was refused and may include a Retry-After header indicating how long to wait before making a new request.
Example: a client performs too many requests on a public API and the server needs to throttle the client so that other clients are not negatively impacted
5xx – Server Error
This class of status code indicates the server encountered an unexpected error when processing the client’s request. Status codes of this class require the server’s administrator to resolve the error. Your REST API should never throw 5xx intentionally. Don’t worry, whatever framework you are building your API in will make sure the proper 5xx status code is returned.
Note: This status code should never be returned intentionally from a REST API. If you can anticipate errors or issues in processing, you should always return a 4xx status code informing the client why their request is unable to processed.