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.

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!