HTTP 状态码全面指南

为什么重要

后端返回 200 OK，却在正文里写 {"error": "Unauthorized"}。前端的通用错误处理只看 状态码 是成功，登录表单陷入死循环。这类细微差错会白白消耗工程时间，更会扭曲 SEO 抓取与死链统计。何时该返回哪个状态码是基本功。

三个真实场景

五大类一览

操作指南 —— 使用状态码参考

打开 HTTP 状态参考。

1. 1

   按编号或描述搜索

   输入「401」「unauthorized」或「rate limit」，匹配项会排到前列。

2. 2

   阅读规范含义

   每条说明不只复述 curl 输出，而是对齐规范表述。

3. 3

   了解实际用法

   注释会点名 GitHub、Stripe、AWS 等常见 API 的细微差异。

4. 4

   关注 SEO 影响

   每条标记搜索引擎处理方式（是否索引、是否传递排名等）。

5. 5

   复制一句话描述

   可直接贴进 API 文档或代码注释。

POST /admin/users
(No Authorization header)

401 Unauthorized
WWW-Authenticate: Bearer realm="admin"

POST /admin/users
Authorization: Bearer eyJ...   (valid token, viewer scope)

403 Forbidden
{"error": "scope_admin_required"}

进阶技巧

• 语义上无效但格式正确的输入用 422（例如 JSON 字段类型不对）。格式损坏才用 400。
• 删除资源返回 204 No Content 比 200 空正文更清晰——表明刻意无负载。
• 429 / 503 务必带 Retry-After，让智能客户端知道何时重试。
• 避免 200 + error: ...。这会毁掉 HTTP 语义，也会让各类监控误判。

常见误区

何时不适合用本参考

• 全新协议设计——HTTP 状态与 HTTP 语义绑定；gRPC、WebSocket 等有各自的约定。
• 应用内错误上报——业务错误码应出现在正文，与 HTTP 码并存。
• 监控仪表盘——APM 应自动归类状态码；本参考服务于上线前的设计决策。

常见问题

下一步

1. 排查怪异行为时用 URL 解析 检视响应相关 URL。
2. 排障时可能用到的命令可查 Git 命令 与 Linux 命令 参考。
3. 502/504 指向上游时，用 IP 查询 核对底层服务器与 ASN。