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.

1xx Informational2xx Success3xx Redirection4xx Client Error5xx Server Error
CodeNameCategoryDescription
100Continue1xx InformationalThe client should continue with the request body.
101Switching Protocols1xx InformationalServer agrees to switch protocols (e.g., upgrade to WebSocket).
102Processing1xx InformationalServer received the request and is still processing it.
200OK2xx SuccessThe request succeeded. Most common status code.
201Created2xx SuccessRequest succeeded and a new resource was created (common for POST).
202Accepted2xx SuccessRequest accepted but not yet processed (async task).
204No Content2xx SuccessRequest succeeded with no content returned (common for DELETE).
206Partial Content2xx SuccessServer returns partial content (Range request).
301Moved Permanently3xx RedirectionResource permanently moved to a new URL. SEO link equity transfers.
302Found3xx RedirectionResource temporarily moved. Does not transfer SEO link equity.
304Not Modified3xx RedirectionResource not modified, client should use cached version.
307Temporary Redirect3xx RedirectionTemporary redirect, preserves the original request method.
308Permanent Redirect3xx RedirectionPermanent redirect, preserves the original request method.
400Bad Request4xx Client ErrorMalformed request syntax or invalid parameters.
401Unauthorized4xx Client ErrorAuthentication required. Common with missing or invalid token.
403Forbidden4xx Client ErrorServer refuses the request (insufficient permissions).
404Not Found4xx Client ErrorRequested resource not found. Most common client error.
405Method Not Allowed4xx Client ErrorHTTP method not allowed (e.g., POST to a GET-only endpoint).
408Request Timeout4xx Client ErrorClient did not send request within server timeout.
409Conflict4xx Client ErrorRequest conflicts with server state (e.g., duplicate creation).
410Gone4xx Client ErrorResource permanently removed (more explicit than 404).
413Payload Too Large4xx Client ErrorRequest body exceeds server limit (e.g., large file upload).
415Unsupported Media Type4xx Client ErrorRequest Content-Type not supported by server.
422Unprocessable Entity4xx Client ErrorWell-formed but semantically erroneous request (validation failure).
429Too Many Requests4xx Client ErrorRate limit exceeded (throttling).
500Internal Server Error5xx Server ErrorUnexpected server error. Most common server error.
501Not Implemented5xx Server ErrorServer does not support the requested feature.
502Bad Gateway5xx Server ErrorGateway/proxy received invalid response from upstream.
503Service Unavailable5xx Server ErrorService temporarily unavailable (overloaded or maintenance).
504Gateway Timeout5xx Server ErrorGateway/proxy timed out waiting for upstream.
511Network Authentication Required5xx Server ErrorNetwork 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.