HTTP Status Codes Reference
HTTP status codes are 3-digit server response identifiers, grouped into 5 categories. This table covers all common codes with descriptions.
How It Works
An HTTP status code is the server's 3-digit reply, and the first digit fixes the class: 1xx informational, 2xx success, 3xx redirection, 4xx client error, 5xx server error. Exact meanings are defined by specs such as RFC 9110, which obsoleted RFC 7231 in 2022.
Status codes pair with methods: 4xx hints the caller should fix something (params, auth, URL), 5xx hints the server broke. Using 301/302/308 redirects correctly is vital for SEO link equity; 429 signals rate limiting and 503 marks temporary unavailability, often with Retry-After.
When to Use This Table
This table is for confirming the precise meaning and class of an HTTP status code. It gives 42 common codes with their English name, Chinese name, class (1xx–5xx) and explanation. Consult it while writing API documentation, reading framework source or debugging endpoint behaviour.
When not to consult it: you are designing a full API error taxonomy or analysing HTTP/2 versus HTTP/3 differences. This table covers the standard HTTP/1.1-era codes, not vendor-specific private codes or semantic alternatives.
Rule of thumb: look at the first digit. 1xx informational, 2xx success, 3xx redirection, 4xx client error, 5xx server error. This five-way split resolves most cases — a 404 means the resource is missing on the client side, while a 502 means the gateway could not get a response from upstream on the server side.
Mind that within a class the codes do not simply escalate in severity. 301 and 302 both redirect but the former is permanent and cached by browsers and intermediaries, and 307/308 preserve the method while 302/303 turn POST into GET. Choosing the wrong one makes behaviour diverge from expectations.
Boundaries and Common Pitfalls
The difference between 502 and 504 is who is at fault, not severity
502 Bad Gateway means the gateway received an invalid response from upstream: connection refused, an empty response after a timeout, or a crashed process. 504 Gateway Timeout means the gateway did not receive a response within the wait window: upstream is slow or stuck. The investigation paths differ completely — for 502 check whether the upstream is running, whether the port is listening and whether load balancer backends are healthy; for 504 check upstream performance, slow queries and connection pool exhaustion. Treating 504 as 502 sends you chasing the wrong cause.
302 turns POST into GET; 307 and 308 preserve the method
This is where subtle bugs hide: a form POSTs to a URL and the server returns 302, so the browser switches to GET and resubmits — the body is lost. XHR clients that follow redirects manually may behave differently again. Use 307 (temporary) or 308 (permanent) when the method must be preserved. Conversely, if you *do* want POST turned into GET, use 302 or 303. Do not mix them: 303 explicitly requires GET while the method after 302 depends on the client implementation.
The choice between 429 and 503 determines how clients back off
429 Too Many Requests means rate limiting — the client is going too fast, usually with Retry-After saying when to retry. 503 Service Unavailable means the service is temporarily unavailable due to overload or maintenance. The difference shapes client strategy: treating 503 as 429 makes clients think the problem is their own rate and retry immediately, worsening the overload. Return 429 with Retry-After for rate limits, and 503 with Retry-After for maintenance windows, so clients respect the stated interval.
How This Relates to Neighbours
For request header semantics such as Cache-Control and Accept, use the in-site HTTP headers page; this one covers status codes only.
For method choice such as PUT versus PATCH and idempotency, use the in-site HTTP methods page, which complements this one.
HTTP/2 multiplexing and HPACK header compression are protocol implementation details, out of scope here.
If the goal is debugging a specific endpoint problem, look at the response body and headers first — the status code gives the category, not the cause.
Practical Snippet
Key points: (1) the first digit gives a five-way split (1xx info, 2xx success, 3xx redirect, 4xx client error, 5xx server error) that resolves most cases; (2) 502 versus 504 is about who is at fault, not severity — 502 means an invalid response (check whether upstream runs and the port listens) while 504 is a timeout (check upstream performance, slow queries, pool exhaustion); (3) 302 turns POST into GET and loses the body, so use 307 or 308 to preserve the method; (4) rate limiting returns 429 and maintenance returns 503, both with Retry-After — confusing them makes clients retry immediately and worsens overload.
// ① Classify by the leading digit
function statusClass(code) {
if (code < 200) return 'info'
if (code < 300) return 'success'
if (code < 400) return 'redirect'
if (code < 500) return 'client-error'
if (code < 600) return 'server-error'
return 'unknown'
}
// ② 502 and 504: completely different investigation paths
function diagnoseGatewayError(code, ctx) {
if (code === 502) {
// Got an invalid response ⇒ the upstream is at fault
return [
'Is the upstream process running: systemctl status / docker ps',
'Is the port listening: ss -tlnp | grep ' + ctx.port,
'Did the load balancer backend health check pass',
]
}
if (code === 504) {
// Timed out waiting ⇒ the upstream is slow or stuck
return [
'Upstream response time: curl -w "%{time_total}" ' + ctx.url,
'Are there slow queries or lock waits',
'Is the connection pool exhausted (DB / HTTP client)',
]
}
return ['Check the response body and headers first; a status code only names the class']
}
// ③ 302 turns POST into GET ⇒ use 307/308 to keep the method
// ❌ res.redirect(302, '/target') the browser may turn POST into GET and drop the body
// ✅ res.redirect(307, '/target') temporary redirect, keeps method and body
// ✅ res.redirect(308, '/target') permanent redirect, keeps the method
// Conversely, to really turn POST into GET ⇒ use 302 or 303 (303 explicitly requires GET)
// ④ Rate limiting uses 429, maintenance/overload uses 503, both with Retry-After
function rateLimited(retryAfterSec) {
return { status: 429, headers: { 'Retry-After': String(retryAfterSec) } }
}
function unavailable(retryAfterSec) {
return { status: 503, headers: { 'Retry-After': String(retryAfterSec) } }
}
console.log(statusClass(404), statusClass(502), statusClass(429))Practical Notes
- 304 and 204 both give fetch an empty body304 (Not Modified) carries no payload, and neither does 204 (No Content). Calling response.json() on either throws. Treat 304 as "reuse the cached copy" and 204 as a successful no-body state instead of parsing it.
- 401 and 403 need completely different handling401 means credentials are missing or invalid, so the client should log in again or refresh its token. 403 means the identity is known but not allowed, so retrying authentication is pointless — treating a 403 as a 401 produces a "refresh token, get 403 again" loop.
- 502/503/504 are gateway errors, not application errorsThey are emitted by a reverse proxy or CDN, which means the request may never have reached the application: 502 upstream sent an invalid response, 503 no healthy instance, 504 upstream timed out. Start from gateway logs and health checks rather than business code.
Data Sources
- RFC 9110 §15
- RFC 9111 (cache-related status codes)
- IANA HTTP Status Code Registry
Codes, names and definitions above come from public specifications; we claim no originality over the specification data itself. The arrangement, Chinese annotations and practical notes on this page are written by us.
| Code | Name | Category | Description |
|---|---|---|---|
| 100 | Continue | 1xx Informational | The client should continue with the request body. |
| 101 | Switching Protocols | 1xx Informational | Server agrees to switch protocols (e.g., upgrade to WebSocket). |
| 102 | Processing | 1xx Informational | Server received the request and is still processing it. |
| 200 | OK | 2xx Success | The request succeeded. Most common status code. |
| 201 | Created | 2xx Success | Request succeeded and a new resource was created (common for POST). |
| 202 | Accepted | 2xx Success | Request accepted but not yet processed (async task). |
| 204 | No Content | 2xx Success | Request succeeded with no content returned (common for DELETE). |
| 206 | Partial Content | 2xx Success | Server returns partial content (Range request). |
| 301 | Moved Permanently | 3xx Redirection | Resource permanently moved to a new URL. SEO link equity transfers. |
| 302 | Found | 3xx Redirection | Resource temporarily moved. Does not transfer SEO link equity. |
| 304 | Not Modified | 3xx Redirection | Resource not modified, client should use cached version. |
| 307 | Temporary Redirect | 3xx Redirection | Temporary redirect, preserves the original request method. |
| 308 | Permanent Redirect | 3xx Redirection | Permanent redirect, preserves the original request method. |
| 400 | Bad Request | 4xx Client Error | Malformed request syntax or invalid parameters. |
| 401 | Unauthorized | 4xx Client Error | Authentication required. Common with missing or invalid token. |
| 403 | Forbidden | 4xx Client Error | Server refuses the request (insufficient permissions). |
| 404 | Not Found | 4xx Client Error | Requested resource not found. Most common client error. |
| 405 | Method Not Allowed | 4xx Client Error | HTTP method not allowed (e.g., POST to a GET-only endpoint). |
| 408 | Request Timeout | 4xx Client Error | Client did not send request within server timeout. |
| 409 | Conflict | 4xx Client Error | Request conflicts with server state (e.g., duplicate creation). |
| 410 | Gone | 4xx Client Error | Resource permanently removed (more explicit than 404). |
| 413 | Payload Too Large | 4xx Client Error | Request body exceeds server limit (e.g., large file upload). |
| 415 | Unsupported Media Type | 4xx Client Error | Request Content-Type not supported by server. |
| 422 | Unprocessable Entity | 4xx Client Error | Well-formed but semantically erroneous request (validation failure). |
| 429 | Too Many Requests | 4xx Client Error | Rate limit exceeded (throttling). |
| 500 | Internal Server Error | 5xx Server Error | Unexpected server error. Most common server error. |
| 501 | Not Implemented | 5xx Server Error | Server does not support the requested feature. |
| 502 | Bad Gateway | 5xx Server Error | Gateway/proxy received invalid response from upstream. |
| 503 | Service Unavailable | 5xx Server Error | Service temporarily unavailable (overloaded or maintenance). |
| 504 | Gateway Timeout | 5xx Server Error | Gateway/proxy timed out waiting for upstream. |
| 511 | Network Authentication Required | 5xx Server Error | Network authentication required (e.g., captive portal). |
Frequently Asked Questions
What is the difference between 301 and 302?
301 is a permanent redirect that transfers SEO link equity to the new URL; 302 is temporary and usually does not transfer equity. 308 / 307 are the method-preserving (e.g. POST) counterparts.
What is the difference between 404 and 410?
404 means the resource was not found (possibly temporarily); 410 means it was permanently removed — more explicit than 404 and helps search engines clean up faster.
What is the difference between 500 and 503?
500 is an unexpected server error; 503 means the service is temporarily unavailable (overload or maintenance), usually with a Retry-After header so crawlers retry later.
What does 429 mean?
Too Many Requests — rate limiting was triggered. The client should slow down and retry according to the Retry-After header.