计算机网络 / 系统课时

排查 4xx 客户端错误

排查 4xx 客户端错误

遇到 4xx 时,不要把所有问题都归结为“参数错误”。有效的处理方式是先根据状态码缩小范围,再依次核对请求方法、地址、参数、认证和权限,并用可重复的请求验证修复前后差异。这样能区分路由错误、身份失效、权限不足和业务校验失败。

学习目标

  • 根据常见 4xx 状态码选择正确的第一检查项。
  • 按 Method、URL、Headers、Body 四类证据定位请求差异。
  • 使用 curl 稳定复现 4xx,并验证修复后的 HTTP 状态。

先根据状态码决定检查方向

状态码是排查入口,不同 4xx 对应的第一检查点不同。记录准确状态码、请求方法、完整 URL 和响应体后,再按下表开始检查,比盲目修改 JSON 参数更有效。

状态码 常见含义 第一检查项
400 请求格式无法被接受 JSON 语法、查询参数格式、Content-Type
401 缺少或无效认证凭据 Authorization、Cookie、Token 有效期
403 身份已识别但没有权限 角色、资源所有权、scope、访问策略
404 路由或资源不存在 Host、路径、API 版本、资源 ID
405 路由存在但方法不允许 GET、POST、PUT、DELETE 与 Allow 响应头
409 当前资源状态与操作冲突 重复创建、版本冲突、并发更新条件
422 请求可解析但语义校验失败 必填字段、类型、枚举值、业务约束
429 请求频率超过限制 限流窗口、重试频率、Retry-After

例如 GET /users/42 返回 200,而 DELETE /users/42 返回 405,首先应该检查路由是否允许 DELETE;如果两种方法都返回 404,再检查路径、Host 和资源 ID。先让状态码决定调查顺序,可以避免无关修改。

HTTP 4xx 按状态码和请求要素定位问题的流程

对照 Method、URL、Headers 和 Body

失败请求应固定成四组证据。Method 检查 GET、POST、PUT、PATCH、DELETE 是否与接口定义一致;URL 拆成 scheme、Host、路径和查询参数;Headers 至少核对认证头和 Content-Type;Body 则检查字段名称、类型、必填项和枚举值。

一个常见错误是只复制 JSON 正文,却没有复制原始方法和 URL。例如 /api/v1/orders 与 /api/v2/orders 可能对应不同路由,POST 与 PUT 也可能分别返回 201 和 405。另一个常见问题是正文实际发送 JSON,却错误设置 Content-Type: application/x-www-form-urlencoded,导致服务器无法按预期解析。

可以先用下面的公开测试端点确认 curl 对状态码的观察方式。该命令不会把响应体写到终端,只输出状态码。

bash
curl -sS -o /dev/null -w 'status=%{http_code}\n' https://httpbin.org/status/404

预期输出

text
status=404

排查自己的接口时,应把 URL 替换为真实目标,并原样带上失败请求使用的方法、必要请求头和正文。只有重放相同请求,修复前后的比较才有意义。

把 401 与 403 分开处理

401 重点检查“身份是否有效”。确认客户端是否发送了凭据、认证方案拼写是否正确、Token 是否过期,以及资源服务器是否认可签发方。使用 HTTP 认证方案时,还可以查看响应里的 WWW-Authenticate,它可能指出需要的认证方式或失败原因。

403 重点检查“这个身份能不能执行该动作”。例如当前用户可以 GET /projects/17,但对同一路径执行 DELETE 返回 403,通常说明路由和资源已经找到,此时应核对角色、资源所有权、Token scope、组织边界或网关策略,而不是先修改 URL。

某些系统会故意对无权查看的资源返回 404,以避免泄露资源是否存在。因此状态码只能确定优先检查方向,最终仍要结合服务端日志、认证结果和权限策略确认根因。

从响应体和响应头提取证据

只记录“返回了 422”通常不足以定位问题。接口如果返回结构化错误信息,应保留业务错误码、字段名、错误消息和请求追踪 ID。例如 422 可能直接指出 email 格式非法,409 可能说明版本号已经过期。具体字段名称以实际接口契约为准,不要假设所有 API 都使用相同的错误结构。

响应头也能提供重要线索。405 响应通常可通过 Allow 告知资源接受哪些方法;429 可能通过 Retry-After 表示建议的重试时间。如果本应返回 JSON 的 API 却返回一整页 HTML,则还应检查请求是否被 CDN、WAF、反向代理或统一错误页提前拦截。

浏览器开发者工具中可以直接在 Network 请求详情的 Headers 和 Response 查看这些信息。排查时至少保存状态码、关键响应头、业务错误码和 request ID,服务端才能利用同一个 ID 关联日志。

用原始请求验证修复

修复完成后不要用另一个更简单的请求证明“系统好了”。如果故障请求是携带 Token 的 POST /orders,验证时仍应使用同样的方法、地址、身份和业务数据,仅修改已经确认错误的那个变量,例如 Token、字段值或路径。

推荐的验证顺序是:先确认原始请求可以稳定复现 4xx;只修正一个明确问题;再次重放请求;最后确认状态进入接口约定的成功结果,或进入预期的下一层业务校验。一次只改变一个关键变量,才能确认真正的根因。

如果浏览器与 curl 使用等价的 Method、URL、Headers 和 Body,却得到不同结果,再比较浏览器自动携带的 Cookie、代理设置和安全策略;如果两端稳定返回同一个 4xx,则应继续检查接口路由、参数校验、认证授权或业务状态,而不是把问题归因于浏览器。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查 4xx 客户端错误

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通