HTTP Status Codes: A Complete Reference Guide for Developers

HTTP status codes are three-digit numbers returned by a server in response to a client's request. They tell the client whether the request succeeded, failed, or requires further action. Understanding these codes is fundamental for building and debugging web applications, REST APIs, and microservices. This guide covers every major category and the most important codes you will encounter in practice.

How Status Codes Are Organized

Status codes are grouped into five classes based on their first digit. Each class indicates a general category of response:

• 1xx (Informational): The request was received and the server is continuing to process it.
• 2xx (Success): The request was successfully received, understood, and accepted.
• 3xx (Redirection): Further action is needed to complete the request, usually a redirect to a different URL.
• 4xx (Client Error): The request contains an error on the client's side (bad syntax, authentication, etc.).
• 5xx (Server Error): The server failed to fulfill a valid request due to an internal problem.

1xx Informational Responses

These codes are rarely encountered in typical web development but are important in specific protocols and scenarios:

• 100 Continue tells the client to continue sending the request body. This is used with the Expect: 100-continue header for large uploads.
• 101 Switching Protocols indicates the server is switching to a different protocol, most commonly seen during WebSocket upgrades.

2xx Success Codes

These are the codes you want to see. They indicate that the request was processed successfully:

• 200 OK is the standard success response. For GET requests, it means the resource was found and returned. For POST or PUT, it means the operation completed and the response body contains the result.
• 201 Created indicates a new resource was successfully created. This is the appropriate response for POST requests that create entities. The response should include a Location header pointing to the new resource.
• 204 No Content means the request succeeded but there is no response body. This is commonly used for DELETE operations and successful PUT/PATCH requests where the client does not need the updated resource back.

3xx Redirection Codes

Redirection codes tell the client that the resource has moved or that a cached version can be used:

• 301 Moved Permanently means the resource has permanently moved to a new URL. Search engines will transfer SEO value to the new URL. Use this when changing URL structures or migrating domains.
• 302 Found indicates a temporary redirect. The client should continue using the original URL for future requests. Common for login redirects and A/B testing.
• 304 Not Modified tells the client that the cached version of the resource is still valid. This code is returned when the client sends conditional headers like If-None-Match or If-Modified-Since, saving bandwidth by not re-transmitting the resource.

4xx Client Error Codes

These codes indicate that the problem is on the client's side. The request needs to be modified before retrying:

• 400 Bad Request means the server cannot process the request due to malformed syntax, invalid parameters, or missing required fields. Always return a descriptive error message in the response body.
• 401 Unauthorized indicates the request lacks valid authentication credentials. Despite the name, this is about authentication (who you are), not authorization (what you can do). The client should authenticate and retry.
• 403 Forbidden means the server understood the request but refuses to authorize it. The client is authenticated but does not have permission to access the resource. Unlike 401, re-authenticating will not help.
• 404 Not Found is the most recognizable status code. The requested resource does not exist at the given URL. APIs should return 404 for missing resources, not an empty 200 response.
• 405 Method Not Allowed means the HTTP method (GET, POST, PUT, etc.) is not supported for the requested resource. The response should include an Allow header listing the supported methods.
• 429 Too Many Requests is the rate limiting response. The client has sent too many requests in a given time window. The response should include a Retry-After header indicating when the client can retry.

5xx Server Error Codes

These codes indicate that the server encountered an unexpected condition that prevented it from fulfilling the request:

• 500 Internal Server Error is the generic catch-all server error. It indicates an unexpected condition on the server side. In production, always log the full error details internally but return a generic message to the client to avoid leaking implementation details.
• 502 Bad Gateway means the server, while acting as a gateway or proxy, received an invalid response from the upstream server. This is common with reverse proxies like Nginx when the application server crashes or is unreachable.
• 503 Service Unavailable indicates the server is temporarily unable to handle requests, usually due to maintenance or overload. A Retry-After header should indicate when the service is expected to be available again.

REST API Best Practices

Choosing the right status code is crucial for building intuitive and debuggable APIs. Here are some guidelines:

• Be specific: Use 201 for creation instead of a generic 200. Use 204 for deletion instead of returning an empty 200 response. Specific codes help clients handle responses without parsing the body.
• Distinguish 401 from 403: Use 401 when the user is not logged in (or the token is expired). Use 403 when the user is authenticated but lacks the required permissions.
• Use 404 for missing resources: Do not return 200 with an empty body or a "not found" message. HTTP clients and middleware rely on status codes for routing and error handling.
• Include error details: For 4xx errors, return a structured error response with a machine-readable code, human-readable message, and optionally a list of field-level validation errors.
• Implement rate limiting headers: Even when not returning 429, include headers like X-RateLimit-Remaining so clients can proactively throttle their requests.

When to Use Which Code

Here is a quick reference for common API operations:

GET    /users/123      → 200 (found) or 404 (not found)
POST   /users           → 201 (created) or 400 (validation error)
PUT    /users/123       → 200 (updated) or 404 (not found)
PATCH  /users/123       → 200 (updated) or 422 (invalid data)
DELETE /users/123       → 204 (deleted) or 404 (not found)

Authentication errors  → 401 (not authenticated)
Permission errors      → 403 (not authorized)
Rate limit exceeded    → 429 (too many requests)
Server crash           → 500 (internal error)
Upstream failure       → 502 (bad gateway)
Maintenance mode       → 503 (service unavailable)

Consistent use of HTTP status codes across your API makes it easier for frontend developers, third-party integrators, and monitoring tools to understand and react to your server's responses. When in doubt, refer to the HTTP specification (RFC 9110) for the definitive guidance on each code's semantics.