Understanding HTTP Status Codes: Complete Reference Guide

Every time you visit a website, your browser sends an HTTP request and receives a response. That response always includes a three-digit status code that tells you exactly what happened — whether the page loaded successfully, the resource moved somewhere else, you don't have permission, or the server crashed. Understanding these codes is essential for web developers, DevOps engineers, and anyone who works with APIs. This guide covers every important HTTP status code with practical explanations and troubleshooting tips.

How HTTP Status Codes Work

HTTP status codes are grouped into five classes based on the first digit:

• 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
• 4xx — Client Error: The request contains an error or cannot be fulfilled
• 5xx — Server Error: The server failed to fulfill a valid request

When you see a status code, the first digit immediately tells you the category of the response. A 2xx is always good news; a 4xx means you did something wrong; a 5xx means the server did something wrong.

1xx — Informational Responses

These are rarely seen by end users but are important for understanding the HTTP protocol:

100 Continue

The server received the request headers and the client should proceed to send the request body. This is used with the Expect: 100-continue header when sending large payloads — the client checks if the server will accept the request before actually sending the data.

101 Switching Protocols

The server is switching to a different protocol as requested by the client. Most commonly seen when upgrading an HTTP connection to WebSocket (Upgrade: websocket).

103 Early Hints

A relatively new status code that lets the server send preliminary headers (like Link headers for preloading resources) before the final response. This can speed up page loads by letting the browser start fetching CSS and JavaScript files while the server is still generating the HTML.

2xx — Success

200 OK

The standard success response. The request succeeded and the response body contains the requested data. This is the most common status code you'll encounter — it's what you get when a page loads normally or an API call returns data successfully.

201 Created

The request succeeded and a new resource was created as a result. Typically returned after a POST request that creates a new record — for example, creating a new user account or adding a blog post. The response usually includes the newly created resource or a Location header pointing to it.

204 No Content

The request succeeded but there's no content to return. Common for DELETE operations — the resource was successfully deleted, and there's nothing to send back. Also used for PUT/PATCH operations where no response body is needed.

206 Partial Content

The server is returning only part of the resource, as requested by the client's Range header. This is how video streaming works — your browser requests chunks of the video file, and the server returns each chunk with a 206 status.

3xx — Redirection

301 Moved Permanently

The resource has been permanently moved to a new URL. Browsers and search engines will automatically update their bookmarks and indexes to point to the new location. Use 301 when a page's URL has changed forever — for example, after a site restructure or domain migration. For SEO, a 301 redirect passes most link equity to the new URL.

302 Found (Temporary Redirect)

The resource is temporarily at a different URL. The original URL should still be used for future requests. Common for temporary redirects during maintenance, A/B testing, or language-based routing. Unlike 301, search engines won't update their index.

304 Not Modified

The resource hasn't changed since the last time the client requested it. The server doesn't send the response body — the client should use its cached version. This saves bandwidth and improves performance. It works with conditional headers like If-Modified-Since and If-None-Match (ETags).

307 Temporary Redirect

Similar to 302, but guarantees that the HTTP method won't change during the redirect. A POST request to the original URL will remain a POST to the new URL. With 302, some older clients might change POST to GET.

308 Permanent Redirect

Like 301, but guarantees the HTTP method is preserved. A POST stays a POST. Use this for permanent API endpoint changes where method preservation matters.

4xx — Client Errors

400 Bad Request

The server can't process the request because of a client error — malformed syntax, invalid request framing, or deceptive request routing. In APIs, this usually means the request body is malformed JSON, missing required fields, or has invalid parameter values.

401 Unauthorized

The request requires authentication, and the client hasn't provided valid credentials. Despite the name, this is about authentication (who you are), not authorization (what you're allowed to do). When building APIs, return 401 when no valid token or credentials are provided. If you're working with API tokens, our guide on decoding JWT tokens can help you debug authentication issues.

403 Forbidden

The server understood the request but refuses to authorize it. Unlike 401, the client's identity is known (or doesn't matter) — they simply don't have permission. This is true authorization failure. An authenticated user trying to access an admin-only endpoint would get a 403.

404 Not Found

The most famous error code on the internet. The server can't find the requested resource. This could mean the URL is wrong, the resource was deleted, or the link is outdated. Every website should have a custom 404 page that helps users find what they're looking for.

405 Method Not Allowed

The HTTP method used is not supported for this endpoint. For example, sending a DELETE request to an endpoint that only accepts GET and POST. The response should include an Allow header listing the permitted methods.

408 Request Timeout

The server timed out waiting for the client to finish sending the request. This happens when the client starts sending a request but doesn't complete it within the server's timeout period — common with slow connections or large file uploads.

409 Conflict

The request conflicts with the current state of the server. Common in REST APIs when trying to create a resource that already exists (duplicate email, username, etc.) or when there's a version conflict during concurrent updates.

413 Payload Too Large

The request body exceeds the server's size limit. Often seen when uploading files that exceed the maximum upload size configured on the server (e.g., Nginx's client_max_body_size).

422 Unprocessable Entity

The server understands the content type and syntax is correct, but it can't process the contained instructions. Popular in REST APIs for validation errors — the JSON is valid but the data doesn't pass business rules (invalid email format, password too short, etc.).

429 Too Many Requests

The client has sent too many requests in a given time period (rate limiting). The response should include a Retry-After header indicating how long to wait. This is essential for API protection — for more on API best practices, see our API testing tools guide.

5xx — Server Errors

500 Internal Server Error

The generic catch-all server error. Something went wrong on the server, but the exact problem isn't specified. This could be an unhandled exception, a bug in the application code, a database connection failure, or any other unexpected condition. Check server logs for the actual error.

502 Bad Gateway

The server acting as a gateway or proxy received an invalid response from the upstream server. Common in reverse proxy setups (Nginx → Node.js, for example) when the upstream application crashes, isn't running, or returns malformed data.

503 Service Unavailable

The server is temporarily unable to handle the request — usually due to maintenance or overloading. Should include a Retry-After header. This is the appropriate status code to return during planned maintenance windows.

504 Gateway Timeout

The server acting as a gateway or proxy didn't receive a timely response from the upstream server. Similar to 502 but specifically about timeouts. Often caused by slow database queries, external API calls that hang, or upstream servers that are overloaded.

Best Practices for Developers

Choosing the Right Status Code

When building APIs, choosing accurate status codes makes your API predictable and self-documenting:

• Use 201 for successful creation, not 200
• Use 204 for successful deletion, not 200 with an empty body
• Use 422 for validation errors, not 400
• Use 401 for missing auth, 403 for insufficient permissions
• Never return 200 with an error message in the body — that's an anti-pattern

Error Response Bodies

Status codes tell you what category of error occurred. The response body should explain the specifics. A well-structured error response includes:

{
    "error": "validation_error",
    "message": "Invalid email format",
    "field": "email",
    "code": "INVALID_FORMAT"
}

Monitoring Status Codes

Track your status code distribution in production. A sudden spike in 500 errors indicates a bug or infrastructure issue. Rising 429 responses suggest you may need to adjust rate limits. Lots of 404s could mean broken links or a recent URL structure change. Tools like Grafana, Datadog, and CloudWatch can visualize these metrics.

Conclusion

HTTP status codes are the foundation of communication between clients and servers. Understanding them helps you build better APIs, debug issues faster, and create more reliable web applications. The key takeaway: use specific, accurate status codes rather than defaulting to generic ones. Your API consumers — and your future debugging self — will appreciate the precision.