HTTP 错误：排查指南
如何区分 4xx 与 5xx，502、503、504 分别说明什么，以及如何系统排查最常见的客户端错误。
先看第一位数字
状态码的第一位数字通常告诉你问题由谁负责。4xx 表示请求有问题，应修复客户端；5xx 表示服务器未能处理一个有效请求，应修复服务器或其依赖；3xx 表示资源发生移动，客户端应跟随跳转。没有改变请求就重试 4xx 没有意义，而对 5xx 使用退避重试通常正是正确做法。
最容易浪费时间的 4xx
- 401 与 403——401 表示缺少认证或认证失败（没有有效令牌）；403 表示你已经认证，但没有访问权限。重新登录不会修复 403。
- 刚部署的 API 返回 404——先检查路由和 base path，再假设数据不存在。
- 405——端点存在，但不支持当前方法，例如对 GET 路由发送 POST。
- 409——请求与当前状态冲突，例如唯一键重复、编辑冲突或版本不匹配。
- 413 / 431——请求体或请求头超过限制，限制通常来自容易被忽略的代理。
- 422——格式正确但语义无效，属于校验错误，与 400 的格式错误不同。
- 429——触发限流。读取 Retry-After，退避，并停止继续轰炸服务。
反向代理三件套：502、503、504
在负载均衡器或反向代理之后，三个 5xx 状态码对应不同的上游故障。502 Bad Gateway 表示代理联系到了上游，但收到无效响应——应用可能崩溃、返回了错误内容，或主动关闭连接；检查应用进程是否运行并监听正确端口。503 Service Unavailable 表示上游明确不可用——可能过载、重启、部署中，或代理主动限流；检查容量、健康检查和部署流水线。504 Gateway Timeout 表示上游接受了请求，但没有在代理超时前响应；通常是慢查询、下游 HTTP 调用或卡住的工作进程。
排查顺序也很自然：502 先问“应用是否正常运行并正确通信？”，503 问“应用是否有能力接受请求？”，504 问“应用正在等待什么？”
一条能收敛的排查循环
复现完全相同的失败请求——方法、路径、请求头和请求体都要一致；如果可以，从服务器本身执行 curl，这能把网络层问题与应用层问题分开。不要只看状态码，还要读取响应体，因为框架和代理会留下指纹。然后沿链路向外排查：5xx 看应用日志，401/403 看中间件和认证配置，502/504 看代理配置，429 看限流规则。大多数“神秘”的 HTTP 错误都能在这条循环的两跳之内定位。