HTTP response codes are critical for web developers and users alike, as they indicate the outcome of an HTTP request between a client (such as a web browser or an API) and a server. These three-digit codes not only inform the client about whether the request was successful but also guide how the client should respond. Let’s dive deeper into what these codes mean, when and how to use them, and common mistakes to avoid.
1xx: Informational Responses
100 Continue
This code informs the client that the initial part of the request has been received, and it can continue sending the rest.
When to use
During large file uploads or multipart form data submissions, a server may send this code to inform the client that the headers are fine, and the body can be transmitted.
Common mistake
Misunderstanding the use of 100 Continue, leading to unnecessary complexity in small applications. It’s primarily used in cases where the server needs confirmation before accepting large data.
101 Switching Protocols
Indicates that the server is switching to a different protocol as requested by the client (e.g., from HTTP to WebSockets).
When to use
In WebSockets or HTTP/2 transitions where the client requests a protocol upgrade.
Common mistake
Using this in scenarios where no protocol switch is actually needed.
2xx: Success
200 OK
This is the most common HTTP code, indicating that the request was successful and the server is returning the expected data.
When to use
For GET or POST requests where the requested resource is returned without issues.
Common mistake
Overuse of 200, especially in situations where other codes (like 201 or 204) would provide more context. For example, after creating a resource, use 201 instead.
201 Created
Indicates that a resource was successfully created on the server, often used in response to POST requests.
When to use
After creating a new resource (such as adding a new item to a database) and returning the URL of the new resource in the Location header.
Common mistake
Returning 200 OK when 201 is more appropriate, especially in APIs where resource creation needs to be distinguished from other operations.
204 No Content
The request was successful, but no content is returned. This is often used for DELETE operations or where the client doesn’t need updated information.
When to use
After successfully deleting a resource or performing an action that doesn’t require a response body.
Common mistake
Returning 204 and still sending a response body, which violates the specification. If data needs to be returned, use 200 OK.
3xx: Redirection
301 Moved Permanently
Indicates that the requested resource has been moved to a new permanent URL, and clients should update their bookmarks or cached URLs.
When to use
When restructuring your website or permanently moving resources.
Common mistake
Using 301 for temporary redirects, which can confuse users and search engines, as they treat the resource as permanently moved.
302 Found
The resource is temporarily located at a different URL, but future requests should still use the original URL.
When to use
For temporary redirections, such as A/B testing or redirecting users to a maintenance page.
Common mistake
Using 302 for permanent moves, which can lead to caching and search engine indexing issues. For permanent changes, use 301.
304 Not Modified
The client’s cached version of the requested resource is still up-to-date, and the server is telling the client that there’s no need to re-download it.
When to use
When handling caching mechanisms with If-Modified-Since or ETag headers.
Common mistake
Not setting cache-control headers properly, leading to unnecessary 200 OK responses and wasted bandwidth.
4xx: Client Errors
400 Bad Request
The server cannot understand the request due to invalid syntax or bad data.
When to use
When the client sends malformed or invalid input, such as a poorly formatted JSON request or missing required parameters.
Common mistake
Overusing 400 for all client-side errors, when more specific codes like 422 (Unprocessable Entity) would provide better clarity.
401 Unauthorized
The client is not authenticated and needs to provide valid credentials.
When to use
When authentication is required but not provided or invalid credentials are sent.
Common mistake
Confusing this with 403 Forbidden. Use 401 only when authentication is required, and 403 when the user is authenticated but lacks the necessary permissions.
403 Forbidden
The client is authenticated, but they do not have permission to access the resource.
When to use
For requests where authentication has succeeded, but the client doesn’t have authorization to access the resource.
Common mistake
Using 403 when the issue is actually with authentication (use 401 for that).
404 Not Found
The requested resource could not be found.
When to use
When the resource or endpoint does not exist, or has been removed from the server.
Common mistake
Using 404 for anything other than missing resources, or failing to provide a custom 404 page, which can confuse users.
5xx: Server Errors
500 Internal Server Error
A generic server-side error.
When to use
For unexpected conditions that prevent the server from processing the request, such as bugs or server misconfigurations.
Common mistake
Overusing 500 for all server-side errors, rather than identifying the actual issue. For example, use 503 for service unavailability or 502 for bad gateway errors.
502 Bad Gateway
The server, acting as a gateway or proxy, received an invalid response from the upstream server.
When to use
When a reverse proxy, load balancer, or another intermediary fails to receive a valid response from an upstream server (e.g., API or database server).
Common mistake
Confusing this with 504 Gateway Timeout, which indicates a delay or timeout from the upstream server rather than an invalid response.
503 Service Unavailable
The server is temporarily unable to handle the request, often due to maintenance or overload.
When to use
During planned downtime, maintenance, or when the server is overloaded, and the system needs to recover.
Common mistake
Failing to include the Retry-After header, which tells the client when to try again. Also, using this for permanent issues instead of fixing underlying server problems.