数据与服务 · 网络与接口

客户端错误4xx Error

4xx 是客户端错误：请求本身有问题，原样重发通常还会失败。按错在哪分成格式、身份、资源、频率四类，每类有对应的客户端下一步；只有 408 超时和 429 限流是重试例外。

4xx 分诊台：每个响应该让客户端干什么

你当客户端。队列里是一批真实 4xx 响应，每个都带统一错误契约。读状态码和 error.code，选一个客户端处理动作；选对，工单盖上对应分组色、亮出该不该重试。

POST/api/orders

error{ code: missing-field, message: 「items 不能为空」 }

客户端收到这个 4xx，下一步该怎么处理？

已正确 0/7

第 1/7 单：收到 400 Bad Request，选一个客户端处理动作。

首位 4 就说明请求本身有问题，原样重发通常还会失败。把 7 张工单归类后，4xx 的共同结构就清楚了。

错在哪成员与含义客户端下一步重试

格式 / 参数400 Bad Request请求格式错；422 Unprocessable格式对但语义错（字段校验失败）标红字段让用户改，保留其他输入否

身份 / 权限401 Unauthorized没登录 / 凭证无效（你是谁）；403 Forbidden登录了但没权限（你能干嘛）401 跳登录刷新 token；403 提示无权限否

资源状态404 Not Found不存在；409 Conflict冲突；410 Gone永久删除404 空状态；409 换名或读最新版本否

频率 / 容量429 Too Many Requests限流（配 Retry-After）读 Retry-After，退避后重试是

离开后记住

4xx 的下一步取决于「错在哪一层」。先看状态码分流，再读 error.code 定位到字段或动作。

先看码、再读 code状态码分流类别，响应体的 error.code 给出稳定可解析的细分原因（如 invalid-email、name-taken）；前端按 code 映射到具体字段或入口。
身份错要分清401 没认出你 → 跳登录、刷新 token、带回原请求；403 认得你但角色不够 → 提示无权限，不要循环刷登录。
资源错给入口404/410 给空状态和返回 / 搜索入口；409 给换名或读最新版本的入口，绝不静默覆盖。
限流要等429 配 Retry-After，客户端读它后退避重试；不要立刻原样重发，否则继续被限流。
边界：不是 4xx 的别硬塞服务端崩了 / 下游挂了 / 超时未处理是 5xx，锅在服务端，客户端重试可能成功——别把客户端参数错返成 500 甩锅。

4xx 响应体应带统一结构，前端才能用一个解析器处理整类错误，而不是每个接口手写 if success。

{ "error": { "code": "invalid-email", "message": "email 缺少 @", "details": { "field": "email" } } }

前端读 status 分流类别（4xx 进客户端修复分支），再读 error.code 把 details.field 映射到对应输入框；网络层、重试逻辑、监控告警都靠状态码统一触发，不用每个接口重复判断。

同一个「下单失败」，返回 422 还是 200+success:false，决定了前端、网关和监控能不能各司其职。

正例422 + 统一 error 契约

前端按 4xx 进客户端修复分支，用 error.code 把 details.field 标红；网关不重试，监控不报警，同类错误能聚合。

用户看到「请补全 items」，保留输入直接改；错误可复现、可分类、可恢复。

反例200 + success:false / 500 甩锅

HTTP 层看到的全是成功或服务端错：CDN 照缓存、重试逻辑不触发、告警乱响；前端必须每个接口手写 if success，一旦漏判就吞掉失败。

把参数错返 500，监控误报故障，值班排查半天发现是用户少填了字段——4xx 语义失效，所有人都白忙。

客户端发 POST 创建项目收到 429 Too Many Requests，响应带 Retry-After: 30，最合适的处理是什么？

术语的技术定义和行为以这些一手或权威资料为准。

和本知识点经常一起出现的概念。