Internet Frontend 01 ๐ HTTP Status Codes Deep Dive
HTTP status codes are the server’s primary vocabulary for telling the client what happened. They are not decorative labels. They are machine-readable outcomes that determine whether a browser caches a response, follows a redirect, retries a request, or shows an error page. The first digit of the three-digit code defines the class, and the class defines the contract: 1xx means the request is still in progress, 2xx means it succeeded, 3xx means the client must take further action, 4xx means the client appears to have erred, and 5xx means the server failed . The last two digits have no categorisation role; they identify the specific outcome within the class .
The deep dive is not a list of codes. It is an understanding of the boundaries between them. The difference between 301 and 302 determines whether a browser updates its bookmarks. The difference between 401 and 403 determines whether the client should retry with credentials or stop trying. The difference between 404 and 410 determines whether a search engine removes the page from its index. The codes are close together in number and far apart in meaning, and the meaning is the contract.
Key point: The first digit of a status code is the class, and the class is the contract. 2xx means the request succeeded, 3xx means the client must act, 4xx means the client erred, and 5xx means the server failed. The specific code within the class is the detail that determines caching, retry, and redirect behaviour.
Why the status code is the contract
The cacheability problem. A 200 OK response is cacheable by default . A 302 Found response is only cacheable if the server includes a Cache-Control or Expires header . A 303 See Other response must not be cached, but the response to the second request might be . The status code is the first signal that the browser’s cache uses to decide whether to store the response, and the headers refine the decision. A 200 with no cache headers is cached heuristically; a 302 with no cache headers is not cached at all.
The redirect-method problem. The 3xx codes differ in how they handle the request method. A 301 Moved Permanently or 302 Found received in response to a POST must not be automatically followed unless the user confirms, because the redirect might change the conditions of the request . A 303 See Other explicitly instructs the client to retrieve the new resource with a GET, which is the code that exists for the “POST, then redirect to a confirmation page” pattern . A 307 Temporary Redirect preserves the original method, which is the code that exists for the “redirect a POST without changing it to a GET” case. The codes are not interchangeable; the method semantics are the difference.
The error-retry problem. A 401 Unauthorized response must include a WWW-Authenticate header with a challenge, and the client may retry with credentials . A 403 Forbidden response means the server understood the request and refuses to authorise it; retrying with the same credentials will not help. A 503 Service Unavailable response means the server is temporarily unable to handle the request, and the client should retry later. A 500 Internal Server Error response means the server encountered an unexpected condition, and the client should not retry the same request. The status code is the retry signal, and the wrong code produces the wrong retry behaviour.
The trade-off. The status code is a single number, and the server must choose it before the response body is written. A server that returns 200 OK with an error message in the body is a server that is hiding the outcome from the client’s cache, its retry logic, and its monitoring. The body is for the human; the status code is for the machine. The two are not substitutes.
a. The 1xx and 2xx classes
The 1xx class is informational. It indicates a provisional response, consisting only of the status line and optional headers, terminated by an empty line . The 100 Continue code is the most common: a client that is about to send a large request body can send an Expect: 100-continue header, and the server responds with 100 Continue to indicate that the body should be sent . The 101 Switching Protocols code is the response to an Upgrade request, which is the mechanism behind WebSocket handshakes. The 103 Early Hints code allows the server to send preliminary headers before the final response, which the browser can use to preload resources.
The 2xx class is the success class. The 200 OK code is the generic success: the request succeeded, and the response body contains the representation . The 201 Created code is the response to a POST that created a new resource; the Location header points to the new resource . The 202 Accepted code means the request was accepted for processing but the processing is not complete; it is the non-committal response for asynchronous operations . The 204 No Content code means the request succeeded but there is no body to send; it is the response for a DELETE or a PUT where the client does not need a body back . The 206 Partial Content code is the response to a range request, which is the mechanism behind resumable downloads and video streaming.
HTTP/1.1 201 Created
Location: /users/42
Content-Type: application/json
{ "id": 42, "name": "Ada" }
The 201 response is the code that tells the client the resource exists and where to find it. A 200 response would tell the client the request succeeded but would not tell it that a new resource was created or where it lives. The 201 is the code that makes the Location header meaningful.
b. The 3xx and 4xx classes
The 3xx class is the redirection class. The 301 Moved Permanently code tells the client that the resource has a new permanent URI, and future references should use it . The 302 Found code tells the client that the resource is temporarily at a different URI, and future requests should continue to use the original URI . The 303 See Other code tells the client to retrieve the new resource with a GET, which is the code for the POST-redirect-GET pattern . The 304 Not Modified code is the cache-validation code: the client’s cached copy is still valid, and the server does not need to send the body . The 307 Temporary Redirect and 308 Permanent Redirect codes are the method-preserving variants of 302 and 301.
The 4xx class is the client-error class. The 400 Bad Request code means the request could not be understood due to malformed syntax . The 401 Unauthorized code means the request requires authentication, and the response must include a WWW-Authenticate challenge . The 403 Forbidden code means the server understood the request but refuses to authorise it. The 404 Not Found code means the server cannot find the requested resource. The 405 Method Not Allowed code means the method is not supported for the resource; the response must include an Allow header listing the supported methods. The 409 Conflict code means the request conflicts with the current state of the resource, which is the code for a concurrent-edit collision. The 410 Gone code means the resource is no longer available and the condition is likely permanent . The 429 Too Many Requests code means the client has sent too many requests in a given amount of time, and the response may include a Retry-After header.
HTTP/1.1 409 Conflict
Content-Type: application/json
{ "error": "The document was modified by another user." }
The 409 response is the code that tells the client the request was well-formed but the state was wrong. A 400 would tell the client the syntax was wrong, which is a different problem. The 409 is the code that makes optimistic concurrency control visible to the client.
c. The 5xx class and the code-choice discipline
The 5xx class is the server-error class. The 500 Internal Server Error code is the generic catch-all: the server encountered an unexpected condition that prevented it from fulfilling the request. The 501 Not Implemented code means the server does not support the functionality required to fulfil the request. The 502 Bad Gateway code means the server, while acting as a gateway or proxy, received an invalid response from an upstream server. The 503 Service Unavailable code means the server is temporarily unable to handle the request, often due to maintenance or overload; the response may include a Retry-After header. The 504 Gateway Timeout code means the server, while acting as a gateway or proxy, did not receive a timely response from an upstream server.
The discipline is the choice between the codes. A 500 is the code for a bug. A 503 is the code for a temporary condition that the client should retry. A 502 or 504 is the code for a problem in the upstream chain, not in the server itself. A server that returns 500 for every failure is a server that hides the difference between a bug, a maintenance window, and an upstream timeout. The monitoring, the alerting, and the client’s retry logic all depend on the distinction.
HTTP/1.1 503 Service Unavailable
Retry-After: 120
Content-Type: application/json
{ "error": "The service is under maintenance. Please retry in 2 minutes." }
The 503 with a Retry-After header is the code that tells the client to wait and try again. A 500 would tell the client the request failed and should not be retried. The distinction is the contract.
Complete Example Session
// ============================================
// PART 1: THE 2XX SUCCESS CODES
// ============================================
// 200 OK โ the generic success.
// GET /users/42 โ 200 with the user body.
// 201 Created โ the resource was created.
// POST /users โ 201 with a Location header.
// 202 Accepted โ the request was accepted for async processing.
// POST /reports โ 202 with a status-monitor URL.
// 204 No Content โ the request succeeded with no body.
// DELETE /users/42 โ 204 with no body.
// 206 Partial Content โ the response is a range.
// GET /video.mp4 with Range: bytes=0-1023 โ 206.
// ============================================
// PART 2: THE 3XX REDIRECT CODES
// ============================================
// 301 Moved Permanently โ the resource has a new permanent URI.
// GET /old-page โ 301 Location: /new-page
// 302 Found โ the resource is temporarily elsewhere.
// GET /dashboard โ 302 Location: /login
// 303 See Other โ the client should GET the new URI.
// POST /orders โ 303 Location: /orders/42/confirmation
// 304 Not Modified โ the cached copy is still valid.
// GET /style.css with If-None-Match: "abc" โ 304
// 307 Temporary Redirect โ preserves the method.
// POST /api/v1/users โ 307 Location: /api/v2/users
// 308 Permanent Redirect โ preserves the method, permanent.
// POST /old-api โ 308 Location: /new-api
// ============================================
// PART 3: THE 4XX CLIENT-ERROR CODES
// ============================================
// 400 Bad Request โ malformed syntax.
// POST /users with invalid JSON โ 400
// 401 Unauthorized โ authentication required.
// GET /admin without credentials โ 401 with WWW-Authenticate
// 403 Forbidden โ authenticated but not authorised.
// GET /admin as a regular user โ 403
// 404 Not Found โ the resource does not exist.
// GET /users/999 โ 404
// 405 Method Not Allowed โ the method is not supported.
// DELETE /users (collection) โ 405 with Allow: GET, POST
// 409 Conflict โ the request conflicts with the state.
// PUT /documents/1 with a stale version โ 409
// 410 Gone โ the resource is permanently unavailable.
// GET /promotions/summer-2020 โ 410
// 429 Too Many Requests โ rate limit exceeded.
// GET /api/data 100 times in a minute โ 429 with Retry-After
// ============================================
// PART 4: THE 5XX SERVER-ERROR CODES
// ============================================
// 500 Internal Server Error โ an unexpected condition.
// GET /users/42 with a database connection error โ 500
// 502 Bad Gateway โ an invalid upstream response.
// GET /api/proxy with an upstream crash โ 502
// 503 Service Unavailable โ a temporary condition.
// GET /health during maintenance โ 503 with Retry-After
// 504 Gateway Timeout โ an upstream timeout.
// GET /api/slow with an upstream timeout โ 504
// ============================================
// PART 5: THE CHOICE BETWEEN 401 AND 403
// ============================================
// 401: the client is not authenticated.
// The response must include a WWW-Authenticate header.
// The client may retry with credentials.
// 403: the client is authenticated but not authorised.
// Retrying with the same credentials will not help.
// ============================================
// PART 6: THE CHOICE BETWEEN 301 AND 302
// ============================================
// 301: permanent. The browser updates bookmarks.
// 302: temporary. The browser keeps the original URL.
// The choice affects SEO and user bookmarks.
// ============================================
// PART 7: THE CHOICE BETWEEN 404 AND 410
// ============================================
// 404: not found. The resource may exist later.
// 410: gone. The resource is permanently unavailable.
// 410 tells the search engine to remove the page from its index.
// ============================================
// PART 8: THE 3XX METHOD PRESERVATION
// ============================================
// 303: change the method to GET.
// 307: preserve the method.
// 308: preserve the method, permanently.
// ============================================
// PART 9: THE CACHEABILITY
// ============================================
// 200: cacheable by default.
// 301, 308: cacheable by default.
// 302, 307: cacheable only with explicit headers.
// 304: the cache revalidation response.
// 500, 502, 503, 504: not cacheable.
// ============================================
// PART 10: THE CHECKLIST
// ============================================
// [ ] The status code matches the outcome, not the body.
// [ ] The 201 response includes a Location header.
// [ ] The 401 response includes a WWW-Authenticate header.
// [ ] The 405 response includes an Allow header.
// [ ] The 429 response includes a Retry-After header.
// [ ] The 503 response includes a Retry-After header.
// [ ] The 301 and 302 choice matches the permanence.
// [ ] The 303 and 307 choice matches the method preservation.
The ten parts covered the success codes, the redirect codes, the client-error codes, the server-error codes, the 401-versus-403 choice, the 301-versus-302 choice, the 404-versus-410 choice, the method preservation, the cacheability, and the checklist. The through-line is that the status code is the contract, and the choice between adjacent codes is the discipline.
Quick Reference
The classes
| Class | Meaning | Example |
|---|---|---|
1xx | Informational | 100 Continue, 101 Switching Protocols |
2xx | Success | 200 OK, 201 Created, 204 No Content |
3xx | Redirection | 301 Moved Permanently, 304 Not Modified |
4xx | Client error | 400 Bad Request, 404 Not Found |
5xx | Server error | 500 Internal Server Error, 503 Service Unavailable |
The adjacent-code choices
| Choice | Meaning |
|---|---|
401 vs 403 | Not authenticated vs authenticated but not authorised |
301 vs 302 | Permanent vs temporary redirect |
303 vs 307 | Change method to GET vs preserve method |
404 vs 410 | May exist later vs permanently gone |
500 vs 503 | Bug vs temporary unavailability |
The required headers
| Code | Required header |
|---|---|
201 | Location |
401 | WWW-Authenticate |
405 | Allow |
429 | Retry-After (recommended) |
503 | Retry-After (recommended) |
Best Practices
โ Do This:
HTTP/1.1 201 Created
Location: /users/42
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api"
HTTP/1.1 503 Service Unavailable
Retry-After: 120
โ Don’t Do This:
HTTP/1.1 200 OK
{ "error": "Not found" }
HTTP/1.1 500 Internal Server Error
Retry-After: 120
Common Pitfalls
| Pitfall | Why It Happens | Fix |
|---|---|---|
A 200 with an error body | The server hides the outcome | Use the correct 4xx or 5xx |
A 500 for a temporary condition | The server does not distinguish | Use 503 with Retry-After |
A 403 for a missing Authorization header | The server conflates auth and authz | Use 401 with WWW-Authenticate |
A 302 for a permanent move | The server uses the wrong code | Use 301 or 308 |
A 303 for a POST that should preserve the method | The server uses the wrong code | Use 307 |
Summary
| Item | Value |
|---|---|
| Classes | 1xx, 2xx, 3xx, 4xx, 5xx |
| Success codes | 200, 201, 202, 204, 206 |
| Redirect codes | 301, 302, 303, 304, 307, 308 |
| Client-error codes | 400, 401, 403, 404, 405, 409, 410, 429 |
| Server-error codes | 500, 502, 503, 504 |
| Required headers | Location, WWW-Authenticate, Allow, Retry-After |
Key takeaways:
- The first digit is the class, and the class is the contract.
2xxmeans the request succeeded,3xxmeans the client must act,4xxmeans the client erred, and5xxmeans the server failed . The specific code within the class is the detail that determines caching, retry, and redirect behaviour. - The
2xxcodes differ in what they promise.200is the generic success,201promises a new resource and aLocationheader,202promises only that the request was accepted, and204promises no body . The choice between them is the choice of what the client can rely on. - The
3xxcodes differ in method preservation and permanence.303changes the method toGET,307preserves the method,301is permanent, and302is temporary . The wrong code changes the client’s behaviour in a way that is visible to the user. - The
4xxcodes differ in retry semantics.401means the client may retry with credentials,403means retrying will not help,404means the resource may exist later, and410means it will not . The wrong code produces the wrong retry behaviour. - The
5xxcodes differ in what the client should do.500means a bug,503means a temporary condition with aRetry-After, and502or504mean the problem is upstream. The distinction is the contract that the monitoring and the retry logic depend on.
Remember: The status code is the server’s contract with the client. It is not a label on the body; it is the machine-readable outcome that determines whether the response is cached, whether the redirect is followed, whether the request is retried, and whether the error is shown. The code must match the outcome, and the choice between adjacent codes is the discipline. A 200 with an error body is a hidden failure. A 500 for a maintenance window is a missed retry. A 403 for a missing credential is a wrong instruction. The codes are close together in number and far apart in meaning, and the meaning is the contract.
Stop using slow, ad-bloated tool sites! ๐คฎ
๐ Search “KandZ Tools” on Google to use many professional utilities for free.
KandZ.me is the ultimate minimalist hub for:
โ
Finance (Mortgage, Interest, Inflation)
โ
Tech (Base64, JSON, Dev Suite, IP)
โ
Health (BMI, BMR, TDEE)
โ
Productivity (Timer, Workspace, QR)
โก๏ธ Fast & Private
๐ No data leaves your device
๐ 100% Free
๐ Use it now: https://tools.kandz.me
๐ Bookmark itโyouโll need it later!