What Do The HTTP Status Codes Mean? Posted in Design Kristopher Sandoval August 16, 2023 HTTP underpins the entirety of the modern web API space. Accordingly, having a firm understanding of how HTTP works is integral for building an API. One of the most foundational aspects of HTTP is the status codes it generates. With that in mind, let’s dive into the HTTP status codes and dissect some of the more common codes the average user might encounter. HTTP Status Code Categories HTTP status codes are grouped into five general categories depending on the purpose of the individual code. These codes are defined by RFC 9110 as part of the ongoing HTTP development and iteration. These categories are as follows: 100 Status Codes: Informational Responses designed to inform the user of specific informational states that are important to be aware of. 200 Status Codes: Successful Responses that inform the user that a request was successful. 300 Status Codes: Redirection Responses that inform the user a redirection has occurred or is required to complete the request as formed. 400 Status Codes: Client Error Responses that notify the user of an error on the client side. 500 Status Codes: Server Error Responses that notify the user of an error on the server side. While many HTTP status codes exist, only a handful are common enough to encounter regularly. It should be noted that non-standard responses are possible but are implemented entirely by the server software and, as such, are not discussed herein. 100 Series: Informational Responses Codes in this series are meant to relay specific information to the end user. 100 Continue The 100 Continue code informs the user that they should continue the request as formed or continue despite the response if said request was already completed. It’s typically used when the server needs the body payload but needs to acknowledge the connection and request has been formed. 101 Switching Protocols This code is used when the client has issued an Upgrade request header, the server has agreed, and thus the protocol is being switched. Developer Use Case for the 100 Series The 100 series of codes are informational, so they should be used when a connected request has some additional information that must be passed along. While most users will never see these codes, those developing systems using your API might need these codes to confirm proper form and function. 200 Series: Successful Responses 200 OK Code 200 is perhaps the most common HTTP code on this list as it is the standard “OK” status code, denoting a successful HTTP request. What this response means will depend on the action taken. For instance, a GET request will result in an HTTP 200 response that indicates retrieval and the related message body. 201 This code confirms that the request has been successful and that a new resource was thus created. This code is most common following a POST or PUT request. 204 Code 204 is a code that indicates a request has been met but that there is no additional information to be returned by the server. This code is most common with requests such as DELETE, where an action must be confirmed that does not result in new information being shared with the client. Developer Use Case for the 200 Series The 200 series is often overlooked. After all, if the request is good, who cares why it’s good? The 200 series is actually very useful as it denotes not just success but the reason for success. In the case of 201, it informs the client about the status of the new resource. With 204, it denotes something has been created but that there is no additional information, which is itself a type of update around the resource status. Accordingly, use the 200 codes routinely, as they give your users the best context and assurance as to the success of their processes. Related: Ultimate Guide To 9 Common HTTP Methods 300 Series: Redirection Responses 301 Moved Permanently A 301 code indicates that the resource location has been permanently changed. The new URL/URI will be provided as part of the response, so developers should ensure that 301s don’t expose endpoints that should not be made public. 304 The 304 status code instructs the client that the browser-cached data is valid for use because a response has not been modified. In essence, this code lets the client know that no new requests are needed and that the existing cached data can be used in its place. 307 Temporary Redirect 307 and 308 are focused on redirects, but 307 crucially denotes that this redirect is temporary in nature. The server will respond with the new URL/URI for the client, but denotes that the HTTP method cannot be changed for the new request. 308 Permanent Redirect Like 307, this code denotes a redirect, but in this case, one that is permanent. It utilizes the HTTP Response location header, and again insists that the HTTP method is not changed in the request to the new provided resource. Developer Use Case for the 300 Series Redirection codes are perhaps one of the most important code categories for API developers. Properly formatted redirection and the communication of the context around that redirection help build out the end customer experience. It’s also helpful for developers who create APIs and systems that leverage the implementation. Therefore, be very careful to ensure you are using the correct 300 codes and surfacing the most accurate and appropriate resource links. 400 Series: Client Error Responses 400 Code 400 states that a client error has created a request that the server cannot understand or process. This general error code can encompass issues like malformed requests, client processing errors, or missing header or body information. 401 This status code indicates a request has been refused because the server requires authentication, but the client has not provided this information. Accordingly, when this code is issued, it indicates the user cannot proceed without providing the requested information. 403 While 401 indicates a refusal due to authentication, 403 suggests a refusal for any other general reason beyond authentication. There are various reasons for this, including permission issues, but authentication flows will be relegated entirely to the 401 code. 404 By far the most common code on the web for the average user, the 404 status code has become an in-joke and a cultural touchstone for many. 404 denotes that a request is valid, but the server can’t find the resource. This can occur for a variety of reasons, such as a poorly formed request or one that is directed to an old resource link. 409 Status code 409 indicates that the request as formed is in conflict with the current state of the resource. Such conflicts often include versioning and obsolescence issues. Therefore, software providers should include information in the documentation on how to resolve 409 conflicts. 410 410 is an interesting code in that it communicates an error and a long-term state. The 410 code states a resource that has been requested is no longer available to the client, and that it will not be available again. This basically says, “you can’t access this, and don’t try in the future.” Developer Use Case for the 400 Series 400 codes are vitally important, as they communicate errors and the context of why they occurred. The 400 series provides so much context for a user just due to the nature of the code — it communicates that an error has occurred, and it’s not the server’s fault, which removes a considerable amount of the early-stage problem solving that typically occurs when errors are being resolved. 500 Series: Server Error Responses 500 500, a very common code, denotes that a server can’t fulfill a request due to an error. 500 is a general error code, so when this appears, you must depend on server logs to determine where the issue occurred and for what reason. If a specific reason is known, and that reason is covered by a specific error code in the 500 series, that particular code will display instead of a generic 500. 502 Bad Gateway Code 502 indicates that an invalid response was generated following a valid request. This code almost always denotes a problem that is outside of the user’s control, but occasionally it can relate to client-cached information or routing data that must be purged to properly issue the request. 503 Service Unavailable This error code is the most straightforward of all the HTTP codes, as it basically just states that the server cannot handle a request because it is entirely unavailable. The reasons for this unavailability are varied but typically include an overloaded server or a server currently undergoing maintenance. When 503 codes are generated, developers should create status pages that explain the specific reason the service is unavailable or, at the very least, a generic page that suggests routes for support or status tracking. 504 Gateway Timeout The 504 code indicates that a server is acting as a gateway but cannot generate a response in an adequate time for the user request. Developer Use Case for the 500 Series Like the 400 series, the 500 series provides much information about the context of a failed request. As such, they should both be documented and handled with care. That said, the 500 series requires a bit more clarity than the 400 series. Whereas the 400 series says a problem occurred and it’s not the server’s fault, the 500 series does the opposite, saying a problem has occurred and it is the server’s fault. Accordingly, providing information about server failures and when they will resolve (if such information is available) can provide additional helpful context to the end user. HTTP Status Codes Help Developer Experience The HTTP status codes are so ubiquitous that they often are forgotten in discussions around user and developer experience. Nevertheless, these codes are usually the first-line communication between developers and end users, so they should be understood and implemented effectively. API devs should consider status codes when developing the underlying code for their services. Having a solid grasp of these codes, and documenting their function within the context of API calls and responses, will ultimately result in a better user and developer experience, helping the end user to diagnose problems and gain a firmer understanding of the holistic system. Did we miss any codes you use often? Let us know in the comments below!