HTTP Status Codes.

What Are HTTP Status Codes?

HTTP status codes are three-digit numbers returned by a server in response to a client's request. They are a fundamental part of the Hypertext Transfer Protocol and serve as a universal language between clients (such as web browsers, mobile apps, or API consumers) and servers. Every time your browser loads a page, calls an API endpoint, or submits a form, the server responds with a status code that tells the client what happened. Understanding these codes is essential for web developers, system administrators, and anyone working with networked applications because they provide immediate feedback about whether a request succeeded, failed, or requires additional action.

Status codes matter because they standardize communication across the entire web. Without them, there would be no consistent way for a client to know whether a resource was found, whether authentication succeeded, or whether a server encountered an internal problem. They also play a critical role in debugging, monitoring, and optimizing applications. When an API returns a 500 Internal Server Error, developers know immediately that something went wrong on the server side. When a CDN returns a 304 Not Modified, browsers know they can safely use a cached version of a resource, saving bandwidth and improving load times. Status codes are also leveraged by search engines, load balancers, reverse proxies, and automated tools to make routing and caching decisions.

The Five Categories

HTTP status codes are organized into five categories, each identified by the first digit of the three-digit number. The categories provide a high-level understanding of the nature of a server's response before you even look at the specific code.

1xx — Informational: These status codes indicate that the request was received and the server is continuing to process it. They are relatively rare in everyday web development. A common example is 100 Continue, which tells the client that it should continue sending the request body. Another is 101 Switching Protocols, used when a server agrees to switch to a different communication protocol, such as upgrading an HTTP connection to a WebSocket connection.

2xx — Success: This category means the request was successfully received, understood, and accepted by the server. The most widely used code in this group is 200 OK, which is the standard response for a successful HTTP request. 201 Created is returned when a new resource has been successfully created, typically after a POST request. 204 No Contentindicates that the request succeeded but there is no content to send back in the response body, which is common after a successful DELETE operation.

3xx — Redirection: These codes tell the client that further action is needed to complete the request. The most frequently encountered is 301 Moved Permanently, which signals that a resource has been permanently moved to a new URL. Search engines transfer link equity to the new address when they see this code. 302 Found is a temporary redirect, while304 Not Modified tells the client that the resource has not changed since the last request, allowing it to use a cached copy.

4xx — Client Error: These status codes indicate that the client made a mistake in the request. 400 Bad Request means the server could not understand the request due to malformed syntax. 401 Unauthorized means the client must authenticate itself before accessing the resource. 403 Forbidden means the server understood the request but is refusing to authorize it. 404 Not Found is perhaps the most famous status code on the web, indicating that the requested resource could not be found. 422 Unprocessable Entitymeans the request was well-formed but contained semantic errors that prevented processing.

5xx — Server Error: These codes indicate that the server failed to fulfill a valid request. 500 Internal Server Error is a generic error message returned when an unexpected condition was encountered. 502 Bad Gateway means that one server on the network received an invalid response from another server. 503 Service Unavailableindicates that the server is temporarily unable to handle the request, usually due to being overloaded or undergoing maintenance.

Most Commonly Used Status Codes

While there are dozens of HTTP status codes defined in the specification, a handful of them appear in the vast majority of real-world applications. Knowing these codes by heart will significantly speed up your debugging and API design process. The codes 200 OK and 201 Created are the bread and butter of successful API responses. Whenever a client sends a valid request and the server processes it without issue, one of these two codes is typically returned. Use 200 for general success and 201 when a new resource has been created.

For redirects, 301 Moved Permanently and 304 Not Modified are the most important. The 301 code is essential for SEO when you restructure your website URLs, ensuring that search engines update their indexes. The 304 code is critical for performance optimization, enabling client-side caching so that browsers do not re-download resources that have not changed.

On the client error side, 400 Bad Request is the go-to response for invalid input, such as missing required fields or malformed JSON. 401 Unauthorized and 403 Forbidden handle authentication and authorization respectively, and the distinction between them is one of the most commonly misunderstood topics in web development. 404 Not Foundis universally recognized and should be returned whenever a client requests a resource that does not exist. 422 Unprocessable Entity is useful for validation errors where the request format is correct but the data itself is invalid.

For server errors, 500 Internal Server Error, 502 Bad Gateway, and503 Service Unavailable cover the majority of scenarios. The 500 code is a catch-all for unexpected server failures. The 502 code frequently appears in microservice architectures or when a reverse proxy cannot reach a backend service. The 503code is particularly useful during planned maintenance windows or when a service is experiencing temporary overload.

How to Choose the Right Status Code for Your API

Choosing the correct status code for your API is not just a matter of following conventions — it has real implications for client behavior, caching, search engine optimization, and developer experience. The general principle is to pick the most specific code that accurately describes the outcome of the request. If a client creates a new resource, return 201 Created instead of a generic200 OK. If a request fails validation, return 400 Bad Request or422 Unprocessable Entity instead of a vague 500 error.

When designing a RESTful API, the HTTP method used in the request often dictates which status codes are appropriate. A successful GET request should return 200 OK. A successful POST request that creates a resource should return 201 Created. A successful PUT or PATCH request should return 200 OK with the updated resource, or 204 No Contentif there is nothing to return. A successful DELETE request should return 204 No Contentor 200 OK with a confirmation message.

For error responses, always include a descriptive error message or error code in the response body to help the client understand what went wrong. The status code alone is often not enough detail. For example, a 400 Bad Request response should include specific information about which field was missing or which value was invalid. This approach makes your API much easier to integrate with and reduces the support burden on your team.

It is also important to consider idempotency when choosing status codes. If a client sends a request and does not receive a response due to a network timeout, it may retry the request. Idempotent operations (like GET, PUT, and DELETE) should return the same status code on every attempt, so that retries do not cause unexpected side effects. Non-idempotent operations (like POST) should use mechanisms such as idempotency keys to prevent duplicate resource creation on retries.

Common Mistakes to Avoid

One of the most frequent mistakes in API development is returning 200 OK for every response, including errors. While this might seem convenient, it breaks the contract that clients rely on. HTTP clients, load balancers, monitoring tools, and CDNs all depend on status codes to make intelligent decisions. When a server returns 200 for an error condition, clients have no standard way to detect that something went wrong without parsing the response body and applying custom logic. This leads to brittle integrations that are difficult to maintain and debug.

Another common source of confusion is the difference between 401 Unauthorized and403 Forbidden. Despite the misleading name of 401, it actually means "unauthenticated" — the client has not provided valid credentials or has not provided any at all. The correct response when credentials are missing or invalid is 401 Unauthorized, which should include a WWW-Authenticate header indicating how the client should authenticate. On the other hand, 403 Forbidden means the server knows who the client is (authentication succeeded) but the client does not have permission to access the requested resource (authorization failed). Mixing these two codes leads to confusing error messages and makes it harder for clients to implement proper error handling.

A third mistake is returning 404 Not Found when you actually mean 403 Forbidden. Some APIs return a 404 for resources that exist but that the requesting user is not allowed to see. This is a security anti-pattern because it leaks information about the existence of resources. If a resource exists but the user should not know about it, return 403 Forbidden. Only return 404 when the resource genuinely does not exist for any user. Similarly, returning 500 Internal Server Error for client-side validation failures is a common anti-pattern. The server did not have an internal error — the client sent invalid data. A400 or 422 status code is the correct choice in that scenario.

Finally, be consistent with your status codes across your entire API. If one endpoint returns422 for validation errors while another returns 400 for the same type of failure, developers integrating with your API will struggle to build reliable error-handling logic. Establish a convention document or an API style guide that defines which status codes are used for which scenarios, and enforce it through code reviews and automated testing.