HTTP状态码完全指南（2026）— API开发者实用参考手册

HTTP状态码不只是背诵题

每个HTTP响应都携带一个三位数的状态码。大多数开发者记得基本的几个——200是成功，404是找不到，500是服务器出错。但完整的图景远比这有趣和实用。

真正理解HTTP状态码意味着能写出更好的API、更快地调试、以及在重定向、缓存和错误处理上做出更明智的决策。这份指南是一份实用参考，而不是RFC条文的搬运。

工作时想快速查询某个状态码？访问HTTP状态码工具，即时获取描述和使用说明。

---

五大类别：建立心智模型

HTTP状态码分为五个类别。第一位数字表示所属类别：

范围	类别	一句话概括
1xx	信息性	"稍等，处理中..."
2xx	成功	"给您。"
3xx	重定向	"在那边。"
4xx	客户端错误	"您的请求有问题。"
5xx	服务端错误	"我们这边出问题了。"

将这个结构记住后，遇到不熟悉的状态码时，仅凭第一位数字就能判断是请求侧问题还是服务端问题。

---

2xx：成功状态码

这些是你希望看到的。但2xx内部各有不同。

200 OK

默认的成功码。请求成功，响应体存在。GET请求的默认值，POST/PUT返回更新后的资源时也用它。

201 Created

成功创建资源时使用——通常响应POST请求。最佳实践是包含指向新资源的Location响应头。

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "张伟", "email": "zhangwei@example.com"}'
# HTTP/2 201
# Location: /users/43

很多API对所有情况都返回200，这能用，但很懒。返回201加Location头能给客户端开发者提供更清晰的接口约定。

204 No Content

请求成功但没有内容可返回。适合DELETE操作，或不需要返回更新资源的PUT/PATCH。

204响应绝不能包含响应体。如果删除后需要返回数据，改用200。

---

3xx：重定向

重定向是开发者犯错最多的地方——SEO和缓存影响很容易被忽视。

301 Moved Permanently

资源已永久移动到新URL。浏览器会无限期缓存此重定向。搜索引擎会将链接权重（PageRank）转移到新URL。

注意：301一旦被缓存就很难撤销，浏览器可能缓存数月。如果不是百分之百确定是永久重定向，用302。

302 Found

临时重定向。浏览器会跟随但不会永久缓存。SEO价值留在原URL。适合A/B测试、维护页面、登录后重定向。

307 / 308

307是302的保留方法版（临时），308是301的保留方法版（永久）。重定向POST请求时，确保方法不会变成GET。

304 Not Modified

客户端发送了条件式GET请求，缓存版本仍然有效。服务端只发送状态码，不带响应体。这就是HTTP缓存高效运作的原理。

---

4xx：客户端错误

客户端发送了有问题的请求。大多数API调试工作在这里进行。

400 Bad Request

请求格式错误的通用码——必填字段缺失、JSON无效、类型不匹配等。响应体要尽可能具体。

{
  "error": "validation_failed",
  "details": [
    { "field": "email", "message": "请输入有效的邮箱地址" },
    { "field": "age", "message": "必须是正整数" }
  ]
}

401 Unauthorized

请求需要认证但客户端未提供或提供了无效凭证。尽管叫"Unauthorized"，这个码实际上关于认证（Authentication），不是授权。

403 Forbidden

客户端已认证，但没有访问该资源的权限。服务器知道你是谁，就是不让进。

这个区别很重要：

• 尝试访问别人的私人数据 → 403
• 没有token访问API → 401
• 访问订阅计划不包含的功能 → 403

404 Not Found

资源不存在。细节：一些API为了避免泄露资源存在与否，对没有访问权限的资源也返回404，而不是403。这在安全敏感场景下是合理的。

409 Conflict

请求与资源当前状态冲突。典型场景：用已存在的邮箱创建用户，或乐观锁冲突。

422 Unprocessable Entity

请求语法正确（JSON可解析、Content-Type正确）但语义上无效——违反了业务规则。很多现代API在验证错误时偏好422而不是400，因为它更精确。

• 400："我连您发的内容都解析不了"
• 422："解析成功了，但这没有意义"

429 Too Many Requests

触发频率限制。应包含Retry-After以及X-RateLimit-*系列响应头。

418 I'm a Teapot

这是RFC 2324中愚人节玩笑里定义的状态码，来自"超文本咖啡壶控制协议"（HTCPCP）。服务器因为是茶壶而拒绝煮咖啡。神奇的是它被真正实现进了浏览器，谷歌还真的对某些请求返回这个状态码。互联网最受欢迎的无用标准，没有之一。

---

5xx：服务端错误

服务端出了问题。客户端没做错任何事。

500 Internal Server Error

通用的"出错了"状态码。通常意味着未处理的异常。记录一切，响应中绝不暴露原始堆栈跟踪，在生产环境设置告警。

502 Bad Gateway

作为网关或代理的服务器从上游服务器收到无效响应。nginx + Node.js环境下，Node进程崩溃或超时时常见。

503 Service Unavailable

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

504 Gateway Timeout

网关未能及时从上游服务器获得响应。慢SQL查询、超时的外部API调用、达到执行时限的Lambda函数的典型症状。

---

REST API设计中的状态码

可以直接用的实战速查表：

GET /users → 200（列表）

GET /users/ → 200（找到）、404（不存在）、403（无权限）

POST /users → 201（已创建）、400/422（验证错误）、409（冲突）

PUT /users/ → 200（更新，带响应体）、204（更新，无响应体）、404、409

DELETE /users/ → 204（已删除）、404（不存在）

一致性是关键

最差的API是不一致的API。决定验证错误用400还是422，更新后是否返回资源（200还是204），然后全局遵守。记录下来。

不要什么都返回200

一些API返回{"success": false, "error": "not found"}但状态码却是200。这会破坏客户端库，让监控变得困难，并忽视了一个完善的标准。请使用正确的状态码。

---

调试速查

出现4xx？ 问题在请求端。检查请求头、请求体、认证信息、Content-Type。

出现5xx？ 问题在服务端。检查日志、上游依赖、资源限制。

返回200但数据不对？ 这时候才是应用逻辑层面的问题——传输层没问题。

# 只检查状态码和响应头
curl -I https://api.example.com/endpoint

# 完整请求/响应详情
curl -v https://api.example.com/endpoint

# 带认证头
curl -v -H "Authorization: Bearer your-token" https://api.example.com/users/me

---

写在最后

HTTP状态码是客户端和服务端开发者之间的通信协议。正确使用它们是一种职业素养——让消费你API的前端开发者和凌晨两点排查生产问题的工程师的工作都更容易。

把HTTP状态码工具收藏起来，工作时随时查阅。