Make Tools
2026-03-28

HTTP 状态码全解

全面的 HTTP 状态码指南，涵盖 1xx 到 5xx 所有常见状态码的含义、使用场景和调试技巧。

HTTPAPI网络

HTTP 状态码概述

HTTP 状态码是服务器对客户端请求的响应状态标识。由三位数字组成，首位数字定义了响应类别。理解这些状态码对于 API 开发、Web 调试和故障排查至关重要。

五个类别一目了然：

  • 1xx — 信息性：请求已接收，继续处理
  • 2xx — 成功：请求已成功接收、理解和接受
  • 3xx — 重定向：需要后续操作才能完成请求
  • 4xx — 客户端错误：请求包含语法错误或无法完成
  • 5xx — 服务端错误：服务器在处理合法请求时发生错误

1xx — 信息性响应

100 Continue

服务器已收到请求头，客户端应继续发送请求体。常用于大文件上传——先发头确认，再发体数据。

PUT /upload HTTP/1.1
Expect: 100-continue
Content-Length: 10485760

# 服务器返回 100 Continue 后，客户端才开始发送数据

101 Switching Protocols

服务器同意切换协议。最常见于 WebSocket 升级：

GET /chat HTTP/1.1
Upgrade: websocket
Connection: Upgrade

2xx — 成功响应

200 OK

最常见的成功状态码。请求已被成功处理，响应体包含结果数据。GET 请求返回资源内容，POST 请求返回操作结果。

201 Created

请求成功且服务器创建了新资源。POST 请求创建实体后的标准响应，应包含 Location 头指向新资源的 URI：

POST /api/users HTTP/1.1
Content-Type: application/json

{"name": "张三", "email": "[email protected]"}

# 响应
HTTP/1.1 201 Created
Location: /api/users/12345

204 No Content

请求成功但响应体为空。适用于 DELETE 操作或不需要返回数据的 PUT/PATCH 更新。

206 Partial Content

服务器返回了部分内容。用于断点续传和流媒体——客户端通过 Range 头请求文件的特定字节范围：

GET /video.mp4 HTTP/1.1
Range: bytes=1000-1999

# 响应
HTTP/1.1 206 Partial Content
Content-Range: bytes 1000-1999/50000

3xx — 重定向

301 Moved Permanently

资源已永久移动到新地址。浏览器和搜索引擎会缓存此重定向。SEO 场景下，旧 URL 的权重会传递给新 URL。

302 Found

临时重定向。浏览器不会缓存，下次仍会请求原地址。注意：虽然语义是"临时"，但大多数浏览器会将 POST 改为 GET。

304 Not Modified

资源未修改，客户端可使用缓存版本。由 If-Modified-Since 或 If-None-Match 条件请求触发，节省带宽：

GET /style.css HTTP/1.1
If-None-Match: "abc123"

# 响应（资源未变）
HTTP/1.1 304 Not Modified
# 无响应体，浏览器使用缓存

307 Temporary Redirect

与 302 类似，但严格要求客户端保持原请求方法。POST 仍然是 POST，不会被改为 GET。

308 Permanent Redirect

与 301 类似，但严格要求客户端保持原请求方法。这是 301 的严格版本。

4xx — 客户端错误

400 Bad Request

请求语法错误或参数无效。API 开发中最常见的客户端错误。返回有意义的错误消息帮助客户端修复问题：

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error": "Invalid email format", "field": "email"}

401 Unauthorized

请求需要身份验证。客户端应提供有效的凭据（通常通过 Authorization 头）。注意：虽然名字叫"Unauthorized"，实际含义是"未认证"（Unauthenticated）。

403 Forbidden

服务器理解请求但拒绝执行。与 401 不同，403 表示已认证但无权限。常见于角色权限检查——用户已登录但没有访问该资源的权限。

404 Not Found

资源不存在。但注意，在安全敏感的场景中，有时用 404 代替 403 来避免暴露资源存在性。

405 Method Not Allowed

请求方法不被目标资源支持。服务器应在 Allow 头中列出支持的方法：

DELETE /api/readonly-resource HTTP/1.1

HTTP/1.1 405 Method Not Allowed
Allow: GET, HEAD

409 Conflict

请求与服务器当前状态冲突。常见于乐观锁场景——资源在读取后已被其他人修改。

422 Unprocessable Entity

请求格式正确但语义错误。例如：JSON 语法正确但字段值不满足业务规则。RESTful API 中常用来替代 400 表示业务逻辑验证失败。

429 Too Many Requests

客户端请求频率超过限制。API 限流的标准响应，应包含 Retry-After 头：

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0

5xx — 服务端错误

500 Internal Server Error

服务器遇到意外错误。这是万能的服务器错误码——但好的 API 应该在日志中记录详细信息，并向客户端返回更有意义的错误。

502 Bad Gateway

网关或代理从上游服务器收到无效响应。在微服务架构中常见——反向代理（如 Nginx）无法从后端服务获取有效响应。

503 Service Unavailable

服务器暂时无法处理请求，可能正在维护或过载。应配合 Retry-After 头告知客户端何时重试：

HTTP/1.1 503 Service Unavailable
Retry-After: 3600

504 Gateway Timeout

网关或代理在规定时间内未从上游服务器收到响应。通常意味着后端服务处理太慢或已宕机。

API 设计中的状态码最佳实践

  1. 使用正确的成功码：创建资源用 201，无返回体用 204，不要什么情况都用 200。
  2. 区分 401 和 403：401 是"你是谁？"，403 是"你没权限"。
  3. 422 优于 400：在 RESTful API 中，用 422 表示业务验证失败，400 表示请求格式错误。
  4. 始终提供错误详情：响应体中包含具体的错误信息、字段名和修复建议。
  5. 限流用 429：配合 Retry-After 和 X-RateLimit-* 头使用。
  6. 5xx 错误不要暴露内部细节：客户端不应该看到堆栈跟踪或数据库错误。

调试 HTTP 状态码

在调试 API 问题时，状态码是你的第一个线索。4xx 问题查客户端代码，5xx 问题查服务器日志。我们的 HTTP 状态码查询工具 提供每个状态码的详细说明、使用场景和示例请求。

总结

HTTP 状态码是 Web 通信的通用语言。正确使用它们让你的 API 更易于理解和调试，错误的使用则会制造困惑。记住：语义要准确，信息要完整，安全要谨慎。需要快速查询任何状态码的详情？用我们的 HTTP 状态码查询工具。

试试这个工具？

打开工具 →
← 返回博客