HTTP Status Code Reference & RFC Lookup
Look up HTTP response codes (1xx, 2xx, 3xx, 4xx, 5xx) with official RFC 9110 specifications, caching rules, and code snippets.
Unlike conventional calculator sites that send your financial numbers, payload data, or code snippets across remote web servers, Affi-Chain processes all mathematical derivations, algorithms, and data parsing 100% locally within your browser sandbox. No tracking cookies, no server-side retention, and zero transmission lag.
What is an HTTP Status Code?
An HTTP Status Code is a 3-digit integer issued by a web server in response to a client's request made via the Hypertext Transfer Protocol (HTTP). Defined authoritatively under the Internet Engineering Task Force (IETF) specification RFC 9110 (which obsoleted RFC 7231 and RFC 2616), status codes serve as the universal communication protocol between clients (browsers, mobile applications, API consumers) and servers (origin applications, reverse proxies, content delivery networks).
The first digit of an HTTP status code establishes its classification category, ranging from protocol-level handshakes to catastrophic gateway failures:
- 1xx (Informational): Request received, protocol handshake continuing.
- 2xx (Successful): The client's action was successfully received, understood, and accepted.
- 3xx (Redirection): Further action must be taken by the user agent to fulfill the request.
- 4xx (Client Error): The request contains bad syntax, invalid parameters, unauthorized authentication tokens, or asks for missing resources.
- 5xx (Server Error): The origin server or intermediary gateway failed to fulfill an apparently valid request due to unhandled exceptions, resource exhaustion, or upstream timeouts.
Failing to implement correct status codes degrades distributed system observability, breaks automated web scrapers and mobile SDKs, and severely damages search engine optimization (SEO) by causing search crawlers like Googlebot to misinterpret transient downtime as permanent deletion.
Comprehensive HTTP Status Codes Reference Matrix
The following matrix categorizes official IETF RFC 9110, RFC 6585, and RFC 7725 status codes, detailing their cacheability and canonical semantic meaning:
| Status Code | Reason Phrase | Category | RFC Specification | Cacheable by Default | Canonical Purpose |
|---|---|---|---|---|---|
100 | Continue | 1xx Informational | RFC 9110 §15.2.1 | No | Server signals client to proceed sending the request body after inspecting Expect: 100-continue. |
101 | Switching Protocols | 1xx Informational | RFC 9110 §15.2.2 | No | Client initiated WebSocket or HTTP/2 upgrade; server confirms protocol handoff. |
200 | OK | 2xx Success | RFC 9110 §15.3.1 | Yes (heuristic) | Standard successful response for payload retrieval (GET), execution (POST), or processing. |
201 | Created | 2xx Success | RFC 9110 §15.3.2 | No | Resource successfully created; response includes Location header pointing to new URI. |
202 | Accepted | 2xx Success | RFC 9110 §15.3.3 | No | Request accepted for asynchronous processing; processing is incomplete and may fail later. |
204 | No Content | 2xx Success | RFC 9110 §15.3.5 | Yes | Action completed successfully; response body is intentionally empty (common for DELETE / PUT). |
206 | Partial Content | 2xx Success | RFC 9110 §15.3.7 | Yes | Byte-range response fulfilling client Range: bytes=0-1023 request for media streaming. |
301 | Moved Permanently | 3xx Redirection | RFC 9110 §15.4.2 | Yes (cacheable) | URI has moved permanently. Search engines transfer PageRank equity. User agents historically rewrite POST to GET. |
302 | Found | 3xx Redirection | RFC 9110 §15.4.3 | No | Temporary redirect. Search engines retain original URI. User agents historically rewrite POST to GET. |
304 | Not Modified | 3xx Redirection | RFC 9110 §15.4.5 | Yes | Resource unedited relative to client's If-None-Match (ETag) or If-Modified-Since cache validation. |
307 | Temporary Redirect | 3xx Redirection | RFC 9110 §15.4.8 | No | Temporary redirect that strictly guarantees the HTTP method and request body remain unchanged. |
308 | Permanent Redirect | 3xx Redirection | RFC 9110 §15.4.9 | Yes (cacheable) | Permanent redirect that strictly guarantees the HTTP method and request body remain unchanged (modern 301). |
400 | Bad Request | 4xx Client Error | RFC 9110 §15.5.1 | No | Malformed JSON body, invalid URL query parameters, or invalid header formatting. |
401 | Unauthorized | 4xx Client Error | RFC 9110 §15.5.2 | No | Authentication required. Response must include WWW-Authenticate challenge header. |
403 | Forbidden | 4xx Client Error | RFC 9110 §15.5.4 | No | Identity authenticated, but caller lacks role-based permissions (RBAC) to access resource. |
404 | Not Found | 4xx Client Error | RFC 9110 §15.5.5 | Yes (heuristic) | Origin server cannot find resource at the requested URI path. |
405 | Method Not Allowed | 4xx Client Error | RFC 9110 §15.5.6 | No | HTTP verb (e.g. DELETE) unsupported for this URI. Must include Allow header with allowed verbs. |
409 | Conflict | 4xx Client Error | RFC 9110 §15.5.10 | No | Edit conflicts with current resource state (e.g., duplicate unique database index or optimistic lock failure). |
410 | Gone | 4xx Client Error | RFC 9110 §15.5.11 | Yes | Resource permanently purged with no forwarding address. Signals search bots to remove index entry immediately. |
422 | Unprocessable Entity | 4xx Client Error | RFC 9110 §15.5.21 | No | Syntax is valid JSON/XML, but semantic domain validation failed (e.g., invalid email string or negative age). |
429 | Too Many Requests | 4xx Client Error | RFC 6585 §4 | No | Rate limit threshold breached. Response should supply Retry-After: <seconds> header. |
451 | Unavailable For Legal Reasons | 4xx Client Error | RFC 7725 §3 | No | Resource blocked by court order, copyright takedown, or national censorship authority. |
500 | Internal Server Error | 5xx Server Error | RFC 9110 §15.6.1 | No | Unhandled runtime exception or fatal software defect encountered inside origin application code. |
502 | Bad Gateway | 5xx Server Error | RFC 9110 §15.6.3 | No | Proxy/load balancer (Nginx, Cloudflare) received an invalid, malformed, or dropped response from upstream backend. |
503 | Service Unavailable | 5xx Server Error | RFC 9110 §15.6.4 | No | Server temporarily overloaded or undergoing scheduled maintenance. Frequently pairs with Retry-After. |
504 | Gateway Timeout | 5xx Server Error | RFC 9110 §15.6.5 | No | Proxy/load balancer timed out waiting for upstream backend execution (e.g., slow database query exceeding 60s). |
Architectural Deep Dive: Critical Status Code Disambiguations
1. The Redirection Dilemma: 301 vs. 302 vs. 307 vs. 308
In the early web (HTTP/1.0 and RFC 1945), when a client submitted a POST form and received a 301 Moved Permanently or 302 Found, web browsers universally violated the HTTP specification by rewriting the subsequent request method to GET, dropping the request body.
To eliminate this ambiguity while preserving backward compatibility, the IETF created 307 Temporary Redirect and 308 Permanent Redirect:
flowchart TD
Req[Incoming Client Request] --> Permanent{Is the URI change permanent?}
Permanent -- Yes --> PresvPerm{Must HTTP Method and Body be strictly preserved?}
PresvPerm -- "Yes (REST APIs, POST/PUT)" --> C308["308 Permanent Redirect"]
PresvPerm -- "No (Web Forms rewriting to GET)" --> C301["301 Moved Permanently"]
Permanent -- No --> PresvTemp{Must HTTP Method and Body be strictly preserved?}
PresvTemp -- "Yes (REST APIs, POST/PUT)" --> C307["307 Temporary Redirect"]
PresvTemp -- "No (Standard Browser Flows)" --> C302["302 Found"]
- 301 Moved Permanently: Tells search crawlers to permanently assign historical link equity (PageRank) to the target URI. Browsers frequently change
POSTtoGET. - 308 Permanent Redirect: Identical link equity transfer as
301, but explicitly forbids the client from changing the HTTP method (e.g., aPOSTremains aPOSTwith identical payload). - 302 Found: Informs user agents of a transient location change. Original URI retains SEO equity. User agents frequently rewrite
POSTtoGET. - 307 Temporary Redirect: Temporary redirect that strictly preserves the original HTTP method and body.
2. Authentication vs. Authorization: 401 Unauthorized vs. 403 Forbidden
Software engineers routinely confuse 401 and 403:
- 401 Unauthorized: Means Unauthenticated. The client has not supplied valid credentials. The server response must return a
WWW-Authenticateheader (e.g.,WWW-Authenticate: Bearer realm="affichain-api"). - 403 Forbidden: Means Unauthorized. The server knows exactly who the client is (identity confirmed), but the client's role or permission scope does not allow access to this resource (e.g., a standard user requesting administrative billing settings). Sending authentication credentials again will not alter the outcome.
3. Deletion Semantics: 404 Not Found vs. 410 Gone
- 404 Not Found: Tells the crawler that the URI is currently missing. Search engines do not instantly purge 404 pages; Googlebot will re-crawl 404 URLs repeatedly over weeks in case the error was accidental.
- 410 Gone: Conveys that the resource has been deliberately and permanently deleted with no replacement. Googlebot purges
410pages from search indexes significantly faster than404pages, conserving crawl budget.
Practical Implementation Examples
Python (FastAPI / Starlette) API Error Handling Architecture
FastAPI provides explicit HTTP exception classes adhering to RFC standards:
from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel, EmailStr
app = FastAPI()
class UserRegistration(BaseModel):
username: str
email: EmailStr
# In-memory mock store
USERS_DB = {"admin": "admin@example.com"}
@app.post("/api/v1/users", status_code=status.HTTP_201_CREATED)
def register_user(user: UserRegistration):
# 409 Conflict: Unique database constraint violation
if user.username in USERS_DB:
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail=f"Username '{user.username}' is already registered."
)
USERS_DB[user.username] = user.email
return {"status": "created", "username": user.username}
@app.get("/api/v1/users/{username}")
def get_user_profile(username: str):
# 410 Gone: Explicitly handled retired account
if username == "deleted_user":
raise HTTPException(
status_code=status.HTTP_410_GONE,
detail="User account permanently deleted under GDPR Article 17."
)
if username not in USERS_DB:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="User not found."
)
return {"username": username, "email": USERS_DB[username]}
Node.js (Express) Rate-Limiting & Idempotent Responses
const express = require('express');
const app = express();
app.use(express.json());
// Middleware for RFC 6585 Rate Limiting
const rateLimiter = (req, res, next) => {
const clientRequests = getRequestCount(req.ip); // Simulated lookup
const MAX_ALLOWED = 100;
if (clientRequests > MAX_ALLOWED) {
res.setHeader('Retry-After', '60');
res.setHeader('X-RateLimit-Limit', MAX_ALLOWED);
res.setHeader('X-RateLimit-Remaining', '0');
return res.status(429).json({
error: 'Too Many Requests',
message: 'Rate limit exceeded. Retry after 60 seconds.'
});
}
next();
};
// 204 No Content for successful resource deletion
app.delete('/api/v1/documents/:id', (req, res) => {
const documentId = req.params.id;
const exists = checkDocumentExists(documentId);
if (!exists) {
return res.status(404).json({ error: 'Document not found' });
}
deleteDocument(documentId);
// RFC 9110 specifies 204 must NOT include a message body
return res.status(204).send();
});
Go (Golang) Standard Library HTTP Status Handling
package main
import (
"encoding/json"
"net/http"
)
type ErrorResponse struct {
Error string `json:"error"`
Code int `json:"code"`
}
func secureHandler(w http.ResponseWriter, r *http.Request) {
authToken := r.Header.Get("Authorization")
// 401 Unauthorized when credential is missing
if authToken == "" {
w.Header().Set("WWW-Authenticate", `Bearer realm="AffichainAuth"`)
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusUnauthorized)
json.NewEncoder(w).Encode(ErrorResponse{
Error: "Missing authentication bearer token",
Code: http.StatusUnauthorized,
})
return
}
// 403 Forbidden when identity is known but lacks required scope
if authToken != "admin-secret-token" {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusForbidden)
json.NewEncoder(w).Encode(ErrorResponse{
Error: "Insufficient privileges for requested tenant",
Code: http.StatusForbidden,
})
return
}
w.WriteHeader(http.StatusOK)
w.Write([]byte(`{"status": "authorized"}`))
}
Reverse Proxy Failure Diagnostics: 500 vs. 502 vs. 503 vs. 504
When debugging production downtime in microservices or web architectures fronted by reverse proxies (Nginx, AWS ALB, Cloudflare, Traefik), distinguishing 5xx status codes identifies the exact failure boundary:
| Failure Code | Responsible Component | Root Cause Diagnostics | Resolution Action |
|---|---|---|---|
500 Internal Server Error | Origin Backend App | Unhandled exception inside Node.js, Python, or Go code. | Inspect application APM logs, stack traces, and unhandled promise rejections. |
502 Bad Gateway | Reverse Proxy / Load Balancer | Upstream socket crashed, dropped connection prematurely, or returned invalid HTTP syntax. | Verify backend service process is alive (systemctl status / docker ps) and listening on the designated port. |
503 Service Unavailable | Origin Backend or Ingress | Origin server is alive but has exhausted thread pools, database connection limits, or is in maintenance mode. | Scale backend replicas, tune connection pooling (max_connections), or verify upstream queue latency. |
504 Gateway Timeout | Reverse Proxy / Load Balancer | Upstream application took longer to respond than the proxy's configured proxy_read_timeout. | Optimize slow SQL queries, offload long computations to async workers (Celery/BullMQ), or increase proxy timeout. |
Critical Edge Cases & Common Implementation Traps
1. Returning 200 OK with Error Payloads (Anti-Pattern)
A widespread anti-pattern in legacy GraphQL and poorly designed REST endpoints is returning 200 OK accompanied by an error body such as {"success": false, "error": "Database error"}. This violates HTTP semantics:
- Intermediary CDNs and proxies cache the response as valid content.
- Automated API monitoring tools (DataDog, Prometheus) fail to register service disruptions.
- HTTP client libraries (Axios, Fetch, Requests) do not throw errors, requiring cumbersome manual payload checks.
2. Including Response Bodies with 204 No Content
RFC 9110 strictly mandates that a 204 No Content response must not include a message body or Content-Length header greater than zero. Including a JSON body with a 204 status code will cause modern HTTP parsers (such as Node.js undici or Go net/http) to throw protocol framing errors or hang while parsing chunked transfers.
3. Forgetting WWW-Authenticate on 401 Responses
RFC 9110 §15.5.2 explicitly requires that any 401 Unauthorized response must return at least one WWW-Authenticate header field identifying the authorization scheme (e.g. WWW-Authenticate: Basic, WWW-Authenticate: Bearer). Omitting this header prevents client HTTP engines from automatically negotiating challenge-response handshakes.