HTTP 状态码完全指南：从 100 到 599 的排障、SEO 与 API 设计用法

HTTP 状态码最有价值的地方不是“背出所有数字”，而是在排障时快速判断问题落在哪一层：请求还没发完整、资源不存在、权限不够、缓存命中、被限流、网关拿不到上游响应，还是服务本身暂时不可用。

有效 HTTP 状态码范围是 100 到 599。客户端遇到不认识的状态码时，应先按首位数字理解类别：1xx 信息响应，2xx 成功，3xx 重定向，4xx 客户端或请求侧错误，5xx 服务器、代理或上游错误。600 以上不是标准 HTTP 状态码。

先用五个大类定位问题

范围	含义	排查方向
1xx	临时信息	请求仍在处理中，通常不作为最终结果处理
2xx	成功	请求被接收、理解并完成，注意是否需要返回正文
3xx	重定向	检查 Location、缓存、永久/临时迁移和请求方法是否保留
4xx	请求侧错误	检查路径、参数、认证、授权、资源生命周期和限流
5xx	服务侧错误	检查应用异常、代理、上游、依赖、超时和维护状态

1xx：最终响应前的临时信号

100 Continue 常用于 Expect: 100-continue，让客户端先确认服务器愿意接收请求体，再上传大文件。101 Switching Protocols 表示服务器同意通过 Upgrade 切换协议。102 Processing 来自 WebDAV，表示请求已收到且仍在处理。103 Early Hints 可在最终响应前提前发送资源提示，例如预加载 CSS、脚本或字体。104 Upload Resumption Supported 与可恢复上传规范相关，实际采用前应核对 IANA 当前登记和客户端支持。

2xx：成功不等于都该返回 200

200 OK 是通用成功响应，但创建资源时 201 Created 更准确，并应尽量配合 Location 指向新资源。异步任务应考虑 202 Accepted，它只表示任务已被接收，不保证最终成功。保存、删除、标记已读这类无需返回正文的操作，可以用 204 No Content，且响应不应包含正文。

206 Partial Content 对断点续传、音视频拖动和大文件分段下载很关键。WebDAV 场景里还会遇到 207 Multi-Status、208 Already Reported。226 IM Used 表示服务器对资源应用了实例操作，现实中较少见。

3xx：重定向最容易影响 SEO 和请求方法

301 Moved Permanently 和 308 Permanent Redirect 都表示永久迁移，但 308 要求保持原请求方法和请求体。302 Found 和 307 Temporary Redirect 都可用于临时重定向，区别同样在于 307 明确要求保持方法。表单提交后跳到结果页，常用 303 See Other，让客户端改用 GET 请求结果页。

304 Not Modified 不是“没有内容”的普通成功响应，而是条件请求命中缓存，客户端可以继续使用本地缓存。305 Use Proxy 已废弃，306 保留不用，新系统不要分配它们。

4xx：请求、资源、身份和频率问题

400 Bad Request 适合请求语法、格式、消息边界或整体编码错误。语法正确但业务语义无法处理时，422 Unprocessable Content 往往更清楚。资源状态冲突、重复创建、乐观锁失败或状态机不允许操作时，用 409 Conflict 比用 400 更能指导客户端修复。

401 Unauthorized 实际表达“未认证”，通常应带 WWW-Authenticate；403 Forbidden 是服务器理解请求但拒绝执行，常见于权限不足、安全策略或 IP 规则。404 Not Found 是找不到或不愿透露是否存在；如果确认资源永久移除，410 Gone 更准确。

接口设计里还要认真处理这些码：405 Method Not Allowed 必须带 Allow；413 Content Too Large 表示请求体过大；415 Unsupported Media Type 多半是 Content-Type 或编码不符合接口要求；425 Too Early 用于拒绝可能被 TLS 0-RTT 重放的请求；428 Precondition Required 可强制客户端携带条件头避免丢失更新；429 Too Many Requests 表示限流，最好配合 Retry-After；431 Request Header Fields Too Large 常见于 Cookie 或认证头过大；451 Unavailable For Legal Reasons 表示因法律原因不可用。

5xx：不要把所有服务侧问题都塞进 500

500 Internal Server Error 是兜底码，不应成为所有异常的默认遮羞布。服务器完全不支持某个功能或方法时，501 Not Implemented 更准确；反向代理从上游收到无效响应时是 502 Bad Gateway；维护、过载或依赖暂时不可用时是 503 Service Unavailable；代理等待上游超时是 504 Gateway Timeout。

505 表示不支持请求使用的 HTTP 主版本。506 是内容协商配置循环。WebDAV 相关的 507 和 508 分别指存储不足和循环检测。511 Network Authentication Required 多见于酒店、机场 Wi-Fi 这类网络接入认证，不是源站登录。

常见非标准码要当作平台约定

真实系统里经常看到 419、440、444、494 到 499、Cloudflare 的 520 到 530，以及 598、599。它们可能很有运维价值，但不是通用 IANA 标准语义。跨平台协议设计不应依赖这些码，文档里也要写清楚它们来自框架、代理、网关还是云厂商。

最容易混淆的几组

• 200 / 201 / 202 / 204：同步完成用 200，创建资源用 201，异步接收用 202，成功但无正文用 204。
• 301 / 302 / 303 / 307 / 308：关注永久性和跳转后是否保持方法。必须保留 POST 时优先考虑 307 或 308。
• 400 / 409 / 422：格式错是 400，资源状态冲突是 409，语义合法但业务无法处理是 422。
• 401 / 403：未认证是 401，认证后仍无权是 403。
• 404 / 410：找不到是 404，确认永久删除是 410。
• 408 / 504：408 是服务器等客户端请求超时，504 是网关等上游响应超时。
• 429 / 503：429 是某个客户端请求太多，503 是服务整体暂时不可用。

API 设计建议

不要所有接口都返回 200，再把失败塞进 JSON 的 code 字段。HTTP 状态码应表达协议层结果，业务细节放到响应正文。错误响应可以参考 RFC 9457 的 application/problem+json：提供 type、title、status、detail 和 instance，既方便机器处理，也不会暴露内部堆栈。

生产环境的 500 不应返回 SQL、文件路径、类名和完整堆栈，而应返回可追踪的请求 ID。自动重试也要谨慎：GET、HEAD 这类幂等请求更适合重试，POST 重试前应有幂等键或业务幂等保证。

参考基准

本文按 IANA HTTP Status Code Registry、RFC 9110、RFC 6585、RFC 4918 和 RFC 9457 的语义整理。状态码登记可能继续变化，正式实现前应核对 IANA 最新注册表。