HTTP 状态码：开发者完整参考指南

什么是 HTTP 状态码？

HTTP 状态码是服务器返回的 3 位数字响应，用于指示客户端请求的结果。当浏览器加载页面时，服务器在发送任何内容之前会先回复一个状态码。理解这些状态码对于 Web 开发者、API 设计者以及任何调试网络问题的人来说都至关重要。

状态码根据其第一位数字分为五类：

最重要的状态码

200 OK

最常见的成功响应。请求成功，响应体包含请求的资源。对网页的 GET 请求返回 200 及 HTML 内容。

201 Created

请求成功并创建了新资源。在成功创建数据库记录的 POST 请求后返回。响应应包含指向新资源的 Location 头。

204 No Content

请求成功但无内容返回。常见于 DELETE 操作或不需要响应体的 PUT 更新。

301 Moved Permanently

资源已永久移动到新 URL。浏览器和搜索引擎会更新其缓存的 URL。用于域名迁移和 URL 重构。

302 Found（临时重定向）

资源临时位于不同的 URL。浏览器遵循重定向，但记住原始 URL 用于后续请求。浏览器在跟随 302 后通常会将 POST 改为 GET。

304 Not Modified

客户端的缓存版本仍然有效。与条件请求（If-Modified-Since、If-None-Match）一起使用。服务器确认资源未更改，节省带宽。

400 Bad Request

由于客户端错误，服务器无法处理请求。请求包含格式错误的语法、无效参数或缺少必填字段。

401 Unauthorized

需要身份验证但未提供或验证失败。响应包含指示身份验证方案的 WWW-Authenticate 头。尽管名称如此，它表示“未认证”。

403 Forbidden

服务器理解请求但拒绝授权。客户端已认证但缺乏权限。与 401 不同，重新认证无济于事。

404 Not Found

服务器找不到请求的资源。URL 可能错误、资源可能已被删除，或访问受限以防止信息泄露。

405 Method Not Allowed

此端点不支持该 HTTP 方法（GET、POST、PUT 等）。响应包含列出支持方法的 Allow 头。

408 Request Timeout

服务器等待请求时超时。客户端可以重复请求。

409 Conflict

请求与服务器当前状态冲突。常见于尝试创建重复资源或更新同时被修改的资源时。

410 Gone

资源已永久消失且无转发地址。与 404 不同，服务器明确指示资源曾经存在但已被移除。

422 Unprocessable Entity

请求格式正确但包含语义错误。常见于 REST API 中 JSON 有效但未通过业务规则验证时。

429 Too Many Requests

速率限制生效。响应通常包含 Retry-After 头。用于防止 API 滥用和 DDoS 攻击。

500 Internal Server Error

通用错误，表示服务器遇到意外情况。未处理服务器异常的兜底状态码。

502 Bad Gateway

服务器充当网关时从上游服务器收到无效响应。常见于负载均衡器无法到达应用服务器时。

503 Service Unavailable

服务器因过载或维护暂时无法处理请求。响应可能包含 Retry-After 头。

504 Gateway Timeout

服务器充当网关时未及时收到上游服务器的响应。

REST API 设计中的状态码

设计良好的 REST API 会合理地使用状态码：

GET /users/123     -> 200 (找到) 或 404 (未找到)
POST /users        -> 201 (已创建) 或 400 (无效输入) 或 409 (重复)
PUT /users/123     -> 200 (已更新) 或 404 (未找到) 或 422 (验证失败)
DELETE /users/123  -> 204 (已删除) 或 404 (未找到)
GET /protected     -> 401 (未认证) 或 403 (未授权)

调试技巧

调试 HTTP 问题时，检查：

1. 状态码类别（4xx = 你的问题，5xx = 他们的问题）
2. 响应体中的错误详情（API 通常包含错误消息）
3. 响应头（重定向的 Location、认证的 WWW-Authenticate、速率限制的 Retry-After）
4. 网络时间（慢速 200 可能表示性能问题）

-> 尝试 HTTP 状态码参考