HTTP状态码：它们的含义以及何时使用

你的API返回200。响应正文说{"error": "Not found"}。

这是错的。状态码存在是有原因的。正确使用它们。

五个类别

1xx — 信息性。实践中很少见。

2xx — 成功。请求有效。

3xx — 重定向。去别的地方。

4xx — 客户端错误。你做错了什么。

5xx — 服务器错误。我们做错了什么。

你实际会用到的码

成功（2xx）

200 OK — 标准成功。用于返回数据的GET请求。

201 Created — 资源被创建。在创建东西的成功POST后使用。

204 No Content — 成功，但没有返回内容。用于不返回数据的DELETE或更新。

客户端错误（4xx）

400 Bad Request — 格式错误的请求。无效的JSON，缺少必需字段，错误的数据类型。

401 Unauthorized — 没有认证。用户需要登录。

403 Forbidden — 已认证但不允许。用户存在但缺少权限。

404 Not Found — 资源不存在。经典的那个。

409 Conflict — 请求与当前状态冲突。重复的用户名，版本不匹配。

422 Unprocessable Entity — 语法上正确但语义上错误。有效的JSON但违反业务规则。

429 Too Many Requests — 速率受限。慢下来。

服务器错误（5xx）

500 Internal Server Error — 通用服务器故障。某些东西崩溃了。

502 Bad Gateway — 上游服务器失败。你的服务器没事，但它依赖的东西不行。

503 Service Unavailable — 暂时关闭。维护或过载。

504 Gateway Timeout — 上游服务器没及时响应。

常见错误

200加正文中的错误。 如果是错误，使用错误状态码。不要让客户端解析正文才知道是否成功。

验证错误用500。 用户提交了坏数据？那是400或422，不是500。服务器没坏——请求坏了。

401 vs 403混淆。 401表示"你是谁？" 403表示"我知道你是谁，但不行。"

所有东西都用404。 "未找到"并不总是正确答案。错误方法？405。速率受限？429。

设计API

要具体。客户端可以智能地处理具体错误。通用错误意味着通用处理。

在正文中包含错误详情：

{
  "error": "validation_failed",
  "message": "Email format is invalid",
  "field": "email"
}

状态码说明问题的类别。正文具体解释。

作为客户端处理状态码

2xx — 解析响应，正常继续。

4xx — 你的错。记录，显示给用户，修复请求。

5xx — 服务器的错。也许用退避重试。也许警报。

3xx — 自动跟随重定向（大多数HTTP客户端会）。

不要只检查200。检查成功（2xx）并适当处理其他情况。

---

状态码是沟通。正确使用它们，API变得自我文档化。误用它们，调试变成猜谜游戏。