HTTP 与 Web 标准 / 系统课时

看懂 4xx 客户端错误

看懂 4xx 客户端错误

接口返回 4xx 时,问题通常不是“服务器挂了”,而是请求本身、身份、权限、资源定位或限流条件没有满足。本节用常见状态码建立排查顺序,让你看到 400、401、403、404、405、409、413、415、429 时能快速判断下一步查哪里。

学习目标

  • 区分常见 4xx 状态码分别在表达什么问题
  • 根据请求方法、认证信息、路径、请求体和限流规则定位根因
  • 避免把所有 4xx 都归结为参数错误或权限不足

先抓住 4xx 的本质

4xx 表示服务器已经收到请求,但认为当前请求无法按预期完成。这里的“客户端错误”并不等于一定是前端代码有 Bug:API 网关改写请求、调用方携带过期令牌、客户端使用旧接口版本,甚至服务端把不存在的资源设计成 404,都可能产生 4xx。

排查时先保留完整的请求上下文:HTTP 方法、URL、查询参数、关键请求头、请求体大小,以及响应状态码和响应体。状态码负责给出错误类别,响应体中的业务错误码、字段名和请求 ID 才能进一步缩小范围。

常见状态码怎么区分

状态码 核心含义 优先检查
400 Bad Request 请求格式或参数无法被服务器接受 JSON 语法、参数类型、必填字段、查询参数
401 Unauthorized 当前请求没有通过身份认证 Authorization、Token 是否缺失或失效
403 Forbidden 身份通常已确认,但没有执行该操作的权限 用户角色、资源权限、访问策略
404 Not Found 目标资源或路由不存在 URL、资源 ID、API 版本、路由配置
405 Method Not Allowed 路径存在,但该 HTTP 方法不被允许 GET、POST、PUT、DELETE 是否用对
409 Conflict 请求与资源当前状态发生冲突 重复创建、版本冲突、状态迁移条件
413 Content Too Large 请求体超过服务器允许的大小 上传文件大小、代理与应用层限制
415 Unsupported Media Type 请求体媒体类型不受支持 Content-Type 与实际请求体格式
429 Too Many Requests 请求频率超过限制 限流窗口、配额、重试策略

其中最容易混淆的是 401 和 403。401 重点回答“你是谁还没有被成功确认”,403 则是“知道你是谁,但这个操作不允许你做”。认证成功后仍然返回 403 时,不要继续反复刷新 Token,应转向检查授权规则。

从请求细节定位问题

例如接口声明只接受 JSON,但客户端实际使用了 text/plain。下面是一个依赖 /orders 接口存在且只接受 application/json 的片段示例:

text
POST /orders HTTP/1.1
Host: api.example.test
Content-Type: text/plain
Content-Length: 14

{"sku":"A100"}

预期结果:服务器可以使用 415 表示请求体的媒体类型不受支持。

text
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json

{"error":"unsupported_media_type"}

这里请求体看起来像 JSON,并不代表服务器会把它当成 JSON。Content-Type 描述的是请求体的媒体类型,因此修复方向是把请求头改为 application/json,而不是修改资源路径或认证信息。

对于其他状态码,也可以使用同样的思路按层排除:400 先看请求格式,401 看认证凭证,403 看授权,404 看资源定位,405 看 HTTP 方法,409 看资源当前状态,413 看请求大小,429 看调用频率和配额。

看到状态码后按顺序排查

面对实际接口错误,可以按照“请求是否正确 → 身份是否有效 → 是否有权限 → 资源是否存在 → 当前状态是否允许操作 → 是否触发平台限制”的顺序检查。这样比根据状态码名称猜测原因更稳定。

例如创建订单返回 409 时,如果请求 JSON 完全合法、认证和权限也正常,就应检查是否使用了已经存在的幂等键、订单号是否重复,或资源状态是否已经变化。409 描述的是冲突,并不等价于参数格式错误。

429 则需要特别关注响应头。服务端可能通过 Retry-After 告知客户端等待时间;客户端应采用退避重试并限制并发,而不是收到 429 后立即高速重放,否则只会持续撞上限流规则。

不要只盯着数字

HTTP 状态码只提供通用语义,真正排错时还要结合响应体中的业务错误码、Content-Type、Allow、Retry-After 等响应头以及服务端日志。尤其是 400 和 409,不同系统可能在边界场景采用不同设计,因此应以接口契约为准。

当你能够先用状态码确定错误类别,再用请求上下文和业务错误信息缩小范围,4xx 就不再是一串需要背诵的数字,而是一套可以直接指导定位动作的诊断信号。

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

目录与阅读设置

阅读设置

17

记录一个想法

看懂 4xx 客户端错误

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

登录哪都通