HTTP Status Codes Reference

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.

// ① 按首位数字分类
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 与 504：排查方向完全不同
function diagnoseGatewayError(code, ctx) {
  if (code === 502) {
    // 收到了无效响应 ⇒ 上游有问题
    return [
      '上游进程是否在跑：systemctl status / docker ps',
      '端口是否监听：ss -tlnp | grep ' + ctx.port,
      '负载均衡后端健康检查是否通过',
    ]
  }
  if (code === 504) {
    // 等待超时 ⇒ 上游慢或卡住
    return [
      '上游响应时间：curl -w "%{time_total}" ' + ctx.url,
      '是否有慢查询或锁等待',
      '连接池是否耗尽（DB / HTTP client）',
    ]
  }
  return ['先看响应体与响应头，状态码只说明大类']
}

// ③ 302 会把 POST 改成 GET ⇒ 需要保方法用 307/308
// ❌ res.redirect(302, '/target')   浏览器可能把 POST 变 GET，body 丢失
// ✅ res.redirect(307, '/target')   临时重定向，保持方法与 body
// ✅ res.redirect(308, '/target')   永久重定向，保持方法
// 反过来：确实想把 POST 转 GET ⇒ 用 302 或 303（303 明确要求 GET）

// ④ 限流用 429，维护/过载用 503，都带 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))