DVkToolkit
← 返回博客
·技术科普

HTTP 状态码完全指南：从 1xx 到 5xx

HTTP 状态码是 Web 开发的基础。本文详细讲解所有 HTTP 状态码的含义、使用场景和最佳实践，帮你快速排查接口问题。

#HTTP#网络协议#状态码#Web开发

为什么需要了解 HTTP 状态码

每个 HTTP 响应都带有一个三位数的状态码，它告诉客户端请求的结果：成功、失败、重定向，还是服务器错误。掌握状态码能帮你快速定位接口问题，提升调试效率。

状态码分类

| 分类 | 范围 | 含义 |

|------|------|------|

| 1xx | 100-199 | 信息性响应（请求已被接收，继续处理） |

| 2xx | 200-299 | 成功响应（请求已成功处理） |

| 3xx | 300-399 | 重定向（需要进一步操作以完成请求） |

| 4xx | 400-499 | 客户端错误（请求有语法错误或无法实现） |

| 5xx | 500-599 | 服务器错误（服务器在处理请求时出错） |

1xx：信息性响应

100 Continue

服务器已收到请求头，客户端应继续发送请求体。常用于大文件上传前的 "预备" 请求（Expect: 100-continue 头）。

101 Switching Protocols

服务器同意切换协议，典型场景是从 HTTP 升级到 WebSocket。

103 Early Hints

在最终响应之前，服务器先返回一些提示，让浏览器提前加载资源（Link rel=preload），优化页面性能。

2xx：成功响应

200 OK

请求成功。GET 请求返回资源，POST 请求返回操作结果。这是最常见的状态码。

HTTP/1.1 200 OK

Content-Type: application/json

{"status": "success", "data": [...]}

201 Created

请求成功，并且服务器创建了新资源。通常用于 POST 创建操作。响应中应包含 Location 头指向新资源地址。

204 No Content

请求成功，但响应体为空。常用于 DELETE 操作，或 PUT 更新操作无需返回内容时。

206 Partial Content

服务器成功处理了部分 GET 请求。用于断点续传（配合 Range 请求头）。

3xx：重定向

301 Moved Permanently

资源已**永久**移动到新地址。搜索引擎会更新索引，浏览器会缓存此重定向。

HTTP/1.1 301 Moved Permanently

Location: https://www.example.com/new-path

302 Found

资源**临时**移动到新地址。搜索引擎不会更新索引（与 301 的区别在于永久性）。

> **注意**：302 的历史语义较混乱，实际开发中推荐用 303 或 307 替代。

304 Not Modified

资源未修改，客户端可以使用缓存的版本。用于协商缓存（配合 If-None-Match 或 If-Modified-Since 头）。

GET /style.css HTTP/1.1

If-None-Match: "abc123"

HTTP/1.1 304 Not Modified

307 Temporary Redirect

临时重定向，且**禁止**将请求方法从 POST 改为 GET（307 保证方法不变，302 在这方面行为不确定）。

308 Permanent Redirect

永久重定向，类似 301，但同样**禁止**改变请求方法。

4xx：客户端错误

400 Bad Request

请求语法错误，服务器无法理解。常见于 JSON 格式错误、参数类型不对等。

// 错误示例：JSON 缺少引号

{"name": Zhang}

// 服务器返回 400

{"error": "Invalid JSON: unexpected token 'Z'"}

401 Unauthorized

请求需要身份认证。常见于未登录就访问需要登录的接口。

HTTP/1.1 401 Unauthorized

WWW-Authenticate: Bearer realm="api"

403 Forbidden

服务器理解请求，但拒绝执行。与 401 的区别：身份已认证，但权限不足。

**常见场景**：普通用户尝试访问管理员接口。

404 Not Found

请求的资源不存在。可能是 URL 拼写错误，或资源已被删除。

> **SEO 提示**：404 对搜索引擎友好，不要返回 200 却显示"页面不存在"——那是黑帽 SEO 手法。

405 Method Not Allowed

请求方法不被允许。例如对只支持 GET 的接口发送 POST 请求。响应中应包含 Allow 头说明允许的方法。

HTTP/1.1 405 Method Not Allowed

Allow: GET, HEAD

409 Conflict

请求冲突。常见于版本冲突（如并发编辑同一资源）或唯一性约束冲突（如注册已存在的用户名）。

413 Payload Too Large

请求体过大，服务器拒绝处理。常用于限制上传文件大小。

429 Too Many Requests

客户端发送请求过于频繁，触发了速率限制（Rate Limiting）。响应中应包含 Retry-After 头提示重试时间。

HTTP/1.1 429 Too Many Requests

Retry-After: 60

{"error": "Rate limit exceeded. Please retry after 60 seconds."}

5xx：服务器错误

500 Internal Server Error

服务器遇到未知错误，无法完成请求。这是最泛化的服务器错误，实际开发中应尽量避免直接返回 500，而应给出更具体的错误码。

502 Bad Gateway

作为网关或代理的服务器，从上游服务器收到了无效响应。常见于 Nginx 反向代理时，后端服务挂掉或超时。

503 Service Unavailable

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

504 Gateway Timeout

网关或代理服务器等待上游服务器响应超时。常见于后端服务响应慢或网络不通。

如何选择合适的状态码

| 场景 | 推荐状态码 |

|------|-----------|

| 获取资源成功 | 200 OK |

| 创建资源成功 | 201 Created |

| 删除/更新成功，无需返回内容 | 204 No Content |

| 需要登录 | 401 Unauthorized |

| 登录了但没权限 | 403 Forbidden |

| 资源不存在 | 404 Not Found |

| 参数校验失败 | 400 Bad Request |

| 请求频率过高 | 429 Too Many Requests |

| 服务器崩溃 | 500 Internal Server Error |

调试技巧

用 curl 查看状态码

# 只显示响应头（含状态码）

curl -I https://api.example.com/users

# 显示详细请求/响应信息

curl -v https://api.example.com/users

用浏览器开发者工具查看

  • 打开 Network 面板（F12）

    • 2. 发起请求

    3. 点击对应请求，查看 **Status** 列

    用 Postman / Insomnia 测试

    这两个 API 测试工具都会在界面上高亮显示状态码，并以颜色区分类型（2xx 绿色、4xx 红色等）。

    总结

    掌握 HTTP 状态码是每位 Web 开发者的基本功。建议把本文加入书签，排查接口问题时第一时间查阅！

    > **Pro Tip**: 设计 RESTful API 时，合理使用状态码能让前端错误处理代码更清晰——不要用 200 包住所有错误返回 {"error": ...}。