HTTP状态码参考

http状态码参考是一个完整且支持搜索的索引库，涵盖了 HTTP 规范中定义的所有状态码 — 从 100 Continue 一直到 511 Network Authentication Required。每个条目均展示了其规范名称、定义该代码的 RFC、该代码的具体含义、何时应当发送、何时不该发送，以及困扰着实际代码库的常见陷阱。通过实时筛选功能和分类标签，您只需点击一下即可在不同的分类之间快速跳转。

与普通的扁平化速查表不同，本工具为每个状态码都提供了专门的微型页面，并带有三个以颜色标识的面板（何时使用 / 何时不用 / 常见陷阱），以及为 Express.js, Django, FastAPI 和 Go net/http 准备的即插即用处理程序。生动的动画线路图展示了请求从客户端到服务器的完整传输过程，以及选定的状态码如何流回客户端 — 这对于想要了解状态码在线路中实际代表什么的新人来说非常有用。

为什么状态码参考指南如此重要

如何使用 http状态码参考

1. 快速查找。 在页面顶部的搜索框中输入状态码（如 404）或名称片段（如 teapot, gateway）并提交。符合条件的条目将以完整的详情面板打开。
2. 按分类浏览。 点击 5 个标签（1xx, 2xx, 3xx, 4xx, 5xx）中的任意一个，即可将网格列表筛选为对应的分类。点击全部可进行重置。
3. 实时筛选。 网格正上方的筛选框会随着您的输入实时收窄卡片的显示范围 — 当您只记得名称的一部分（例如 too many 或 precondition）时非常有用。
4. 查看状态码详情。 点击任意卡片即可打开其详情面板。您将看到该代码的含义、何时使用、何时不使用、常见陷阱，以及支持 4 种框架的代码片段块。
5. 复制完整代码。 切换不同框架的标签页，利用精巧的复制按钮即可轻松获取可直接粘贴的处理程序。
6. 对比邻近状态码。 详情面板的末尾附带了来自同一分类（1xx / 2xx / 3xx / 4xx / 5xx）的兄弟状态码卡片，方便您进行快速横向对比。

五大 HTTP 状态码分类一览

容易混淆的状态码对

• 401 与 403。 401 表示未验证身份 — 请求缺乏有效的凭证。403 表示已验证身份但不允许访问 — 凭证虽然有效，但该用户缺乏对应的访问权限。
• 404 与 410。 404 表示未知资源：可能是由于拼写错误，或者它存在于其他未知地方。410 表示资源已被刻意删除：搜索引擎应当直接将其从索引中移除。
• 301 vs 302 vs 307 vs 308。 301 和 308 是永久性重定向（308 严格保留请求方法和请求体），302 和 307 是临时性重定向（307 严格保留请求方法和请求体）。对于 POST / PUT / PATCH 请求的重定向，请优先使用 307 / 308。
• 400 与 422。 400 通常意味着请求体格式错误（比如非法的 JSON，或者缺失了必要的字段）。422 则表示请求体被成功解析，但其数值未能通过业务逻辑规则验证（如电子邮箱格式不正确，或数量超出了允许的范围）。
• 502 vs 503 vs 504。 502 表示上游服务器返回了无效或垃圾数据。503 表示服务器目前超载或正在进行停机维护。504 则表示上游服务器未能按时响应代理的请求。
• 409 与 412。 409 是指与资源的当前状态冲突。412 特指先决条件响应头（如 If-Match, If-Unmodified-Since）在服务器端评估为假（False）。

与特定状态码配合使用的响应头

• 201 Created — 应当包含 Location 响应头，指向新创建的资源地址。
• 301 / 302 / 307 / 308 — 必须包含 Location 响应头，指明目标重定向 URL。
• 304 Not Modified — 必须原样返回本应出现在 200 响应中的响应头（如 ETag, Cache-Control, Vary）。
• 401 Unauthorized — 必须包含 WWW-Authenticate 响应头，列出可接受的验证方案（如 Basic, Bearer）。
• 405 Method Not Allowed — 必须包含 Allow 响应头，列出当前资源所允许的请求方法。
• 413 / 429 / 503 — 通常建议包含 Retry-After 响应头（秒数或 HTTP 日期格式），以便客户端正确执行退避重试。
• 416 Range Not Satisfiable — 必须包含 Content-Range: bytes */<length>。

几乎可以完全忽略的状态码

有一小部分状态码虽然在技术上有效，但在现代 API 中极少露面：305 Use Proxy（已被废弃）、306（保留状态码，未使用）、305、506 Variant Also Negotiates、510 Not Extended 以及 508 Loop Detected。绝大多数是被保留在注册表中以供历史参考。如果您的程序库或中间件触发了其中之一，通常应将其视为该库本身的一个 Bug — 而非提示您需要去进行特殊处理。

常见问题

该工具是否包含来自 RFC 9110 之外的其他规范的状态码？

是的。本工具不仅涵盖了 RFC 9110（HTTP 语义），还涵盖了 RFC 6585（补充的 4xx / 5xx）、RFC 4918（WebDAV）、RFC 5842（WebDAV 绑定）、RFC 7725（451）、RFC 8297（103 Early Hints）、RFC 8470（425 Too Early），以及著名的趣味性文献 RFC 2324（418 Teapot）。

这些状态码在 HTTP/2 和 HTTP/3 中有效吗？

有效。状态码的语义完全是在 RFC 9110 中定义的，这是一份与具体版本无关的 HTTP 语义基准文档。HTTP/2（RFC 9113）和 HTTP/3（RFC 9114）仅仅是对分帧和底层传输进行了重构。

我可以直接链接到某个特定的状态码吗？

可以。您只需在表单中提交单个代码（例如 404），表单下方就会加载出对应的详情面板。此时浏览器地址栏中生成的 URL 包含了您的搜索条件，您可以放心分享 — 打开它会加载出完全相同的结果。

为什么我的应用框架不允许我返回 418 状态码？

某些 HTTP 库的早期版本会拒绝发送那些未内置在其内部注册表中的代码。解决办法是升级该代码库，或者在可行的情况下选择手动编写并输出状态行。

API 是否应该返回带有错误主体的 200 状态码？

不应该。各种监控系统、重试机制以及网络中间件都默认 2xx 代表成功。如果您必须返回结构化的错误信息，请返回与之契合的 4xx 或 5xx 状态码，并将具体的结构化详情放置在响应体中。HTTP API 的 Problem Details 格式（RFC 9457）是一个非常好的参考模板。

是否存在 HTTP 状态码的官方权威注册表？

是的。IANA 在 iana.org/assignments/http-status-codes 维护着官方的注册表。本工具将始终与该注册表以及最常引用的 RFC 规范保持完全同步。