HTTP 状态码
HTTP 状态码是服务器对客户端请求的响应标识，由三位数字组成，第一位数字定义了响应的类别。
状态码分类
- 1xx：信息性状态码，表示请求已接收，继续处理
- 2xx：成功状态码，表示请求已成功被服务器接收、理解并接受
- 3xx：重定向状态码，表示需要客户端采取进一步操作才能完成请求
- 4xx：客户端错误状态码，表示请求包含语法错误或无法完成请求
- 5xx：服务器错误状态码，表示服务器在处理请求的过程中发生了错误
3XX 重定向状态码
重定向状态码表示客户端需要采取进一步的操作才能完成请求，通常用于 URL 跳转。
完整的 3XX 状态码对比
| 状态码 | 名称 | 含义 | 是否缓存 | 请求方法 | 浏览器行为 | 使用场景 |
|---|---|---|---|---|---|---|
| 301 | Moved Permanently | 永久重定向 | ✅ 缓存 | 可能改变为 GET | 首次跳转后缓存规则，下次直接访问新地址 | HTTP→HTTPS，旧域名→新域名 |
| 302 | Found | 临时重定向 | ❌ 不缓存 | 可能改变为 GET | 每次都先请求原地址，再跳转到新地址 | 临时维护页面，A/B 测试 |
| 303 | See Other | 查看其他位置 | ❌ 不缓存 | 强制改为 GET | 强制使用 GET 请求新地址，防止表单重复提交 | POST 后重定向到结果页（PRG 模式） |
| 304 | Not Modified | 未修改 | ✅ 使用缓存 | 保持原方法 | 直接使用本地缓存，不重新下载资源 | 浏览器缓存验证 |
| 307 | Temporary Redirect | 临时重定向 | ❌ 不缓存 | 严格保持原方法 | 每次都先请求原地址，保持原请求方法跳转 | 临时重定向 POST 请求 |
| 308 | Permanent Redirect | 永久重定向 | ✅ 缓存 | 严格保持原方法 | 首次跳转后缓存规则，保持原请求方法访问新地址 | HTTP→HTTPS（保持 POST） |
4XX 客户端错误状态码
4xx 表示请求端存在问题：可能是参数不合法、缺少权限、资源不存在、触发限流等。对 API 调用方来说，4xx 通常意味着“修请求”而不是“重试”。
常见的 4XX 状态码
| 状态码 | 名称 | 含义 | 典型场景 | 调用方建议 |
|---|---|---|---|---|
| 400 | Bad Request | 请求格式或参数错误 | JSON 解析失败、参数类型不对、缺少必填字段 | 修正请求后再发；可在前端做校验 |
| 401 | Unauthorized | 未认证（缺少/无效凭证） | Token 过期、未登录访问受保护资源 | 重新登录/刷新 Token；不要盲目重试 |
| 403 | Forbidden | 已认证但无权限 | RBAC/ACL 拒绝、资源归属不匹配 | 检查权限配置；提示无权限 |
| 404 | Not Found | 资源不存在或路由不存在 | URL 错误、资源已删除、ID 不存在 | 检查路径与 ID；通常不重试 |
| 405 | Method Not Allowed | 方法不被允许 | 对只支持 GET 的资源发 POST | 改用允许的方法 |
| 409 | Conflict | 冲突（状态/版本不一致） | 并发更新冲突、重复创建、幂等键冲突 | 结合业务做重试/提示；必要时先刷新状态 |
| 410 | Gone | 资源已永久移除 | 旧链接对应资源已下线 | 更新引用；不应重试 |
| 413 | Payload Too Large | 请求体过大 | 上传文件/请求体超限 | 压缩/分片上传；调整限制配置 |
| 415 | Unsupported Media Type | 不支持的媒体类型 | Content-Type 不正确（应为 application/json 等） | 修正 Content-Type 与编码方式 |
| 422 | Unprocessable Content | 语义校验失败 | 字段格式合法但业务规则不满足 | 根据错误信息修正数据 |
| 429 | Too Many Requests | 触发限流 | 短时间请求过多 | 按 Retry-After/退避策略重试 |
401 与 403 的区别
- 401：你是谁还不确定（缺少或无效的认证信息）
- 403：你是谁确定了，但你不能做（权限不足）
404 与 410 的区别
- 404：找不到（可能是路径写错，也可能是资源不存在）
- 410：明确告知资源“曾经存在但已永久移除”（适合迁移/下线场景）
5XX 服务器错误状态码
5xx 表示服务端处理请求时发生错误：可能是代码异常、依赖服务不可用、网关转发失败等。对调用方来说，5xx 往往意味着“可以重试”，但应配合超时、熔断、退避和幂等设计。
常见的 5XX 状态码
| 状态码 | 名称 | 含义 | 常见原因 | 调用方建议 |
|---|---|---|---|---|
| 500 | Internal Server Error | 服务端未知错误 | 未捕获异常、错误配置、代码 bug | 可重试少量次数；同时上报/告警 |
| 501 | Not Implemented | 服务器不支持该能力 | 接口未实现、方法不支持 | 停止调用；检查版本与文档 |
| 502 | Bad Gateway | 网关/代理收到上游无效响应 | 上游服务重启、容器未就绪、反向代理转发失败 | 短暂重试；关注上游健康与网关配置 |
| 503 | Service Unavailable | 服务不可用（临时） | 维护模式、过载、实例全下线 | 按 Retry-After 重试；必要时降级 |
| 504 | Gateway Timeout | 网关等待上游超时 | 上游响应慢、网络问题、超时配置过短 | 退避重试；排查超时链路与慢查询 |
502 与 504 的区别
- 502：上游“没给出有效响应”（连接不上、响应格式不对等）
- 504：上游“给得太慢”（网关等不到结果超时）