4. 错误类型分类：客户端错误(4xx)、服务端错误(5xx)、业务逻辑错误、基础设施错误
在API设计治理中，错误类型的准确分类是定义事务边界和移植适配策略的基础。不同类型的错误在事务回滚、重试策略、幂等性保障和客户端补偿机制上具有截然不同的处理要求。本章将错误划分为四个核心类别：客户端错误、服务端错误、业务逻辑错误和基础设施错误，并分析其在事务边界中的行为特征。
4.1 错误分类总览
下表从错误来源、HTTP状态码范围、事务影响和典型场景四个维度，对四类错误进行横向对比：
| 错误类别 | 错误来源 | HTTP状态码 | 事务影响 | 典型场景 |
|---|---|---|---|---|
| 客户端错误 | 请求方（调用者） | 4xx | 事务不应重试，需客户端修正 | 参数校验失败、鉴权过期、资源不存在 |
| 服务端错误 | 服务方（被调用者） | 5xx | 事务可重试，需幂等保护 | 数据库超时、内部异常、网关超时 |
| 业务逻辑错误 | 业务规则约束 | 200/4xx（自定义） | 事务需回滚或补偿 | 余额不足、库存不足、状态冲突 |
| 基础设施错误 | 网络/中间件/硬件 | 5xx / 连接异常 | 事务需降级或熔断 | 网络分区、磁盘故障、DNS解析失败 |
关键原则：客户端错误（4xx）永远不应触发事务重试；服务端错误（5xx）应配合指数退避重试；业务逻辑错误需要明确的补偿接口；基础设施错误需要熔断和降级策略。
4.2 客户端错误（4xx）
客户端错误表示请求本身存在问题，服务端无法或不愿处理该请求。这类错误在事务边界中的核心特征是：不可重试。重试相同的请求只会得到相同的错误响应，且可能加剧服务端资源消耗。
4.2.1 常见客户端错误码
- 400 Bad Request — 请求格式错误、参数缺失或类型不匹配
- 401 Unauthorized — 身份认证失败或令牌过期
- 403 Forbidden — 认证通过但无操作权限
- 404 Not Found — 请求的资源不存在
- 409 Conflict — 资源当前状态与请求冲突（如版本号不匹配）
- 422 Unprocessable Entity — 语义错误，业务规则校验失败
- 429 Too Many Requests — 请求频率超过限流阈值
4.2.2 事务边界适配策略
- 客户端收到4xx后，立即终止当前事务，不发起自动重试
- 将错误信息返回给上层调用者，由人工或客户端逻辑修正请求
- 对于409冲突，可引导客户端获取最新资源状态后重新提交
- 对于429限流，可等待Retry-After头部指定的时间后重试（但属于限流特例）
4.3 服务端错误（5xx）
服务端错误表示服务端在处理请求时发生故障，但请求本身可能是合法的。这类错误在事务边界中的核心特征是：可重试，但必须配合幂等性保障。
4.3.1 常见服务端错误码
- 500 Internal Server Error — 服务端未捕获的通用错误
- 502 Bad Gateway — 上游服务返回无效响应
- 503 Service Unavailable — 服务暂时过载或维护中
- 504 Gateway Timeout — 上游服务响应超时
4.3.2 事务边界适配策略
- 客户端应实现指数退避重试（Exponential Backoff），避免雪崩效应
- 服务端需保证幂等性：同一请求多次执行产生相同结果
- 对于503，可结合Retry-After头部控制重试窗口
- 重试次数应有限制（通常3~5次），超过后进入降级流程
实践建议：在分布式事务中，服务端错误（5xx）不应自动回滚整个事务。应记录事务状态为“待重试”，由事务协调器在后续周期中重新调度，避免因瞬时故障导致长事务整体失败。
4.4 业务逻辑错误
业务逻辑错误并非HTTP协议层面的错误，而是业务规则约束导致的失败。这类错误通常返回200 OK并在响应体中携带业务错误码，或使用422/409等语义化状态码。在事务边界中，业务逻辑错误需要明确的补偿动作或事务回滚。
4.4.1 典型业务逻辑错误场景
- 余额不足 — 扣款操作无法完成
- 库存不足 — 下单时商品库存已被占用
- 状态冲突 — 订单已支付，无法再次取消
- 重复操作 — 幂等校验发现请求已处理
- 依赖条件不满足 — 用户未实名认证，无法提现
4.4.2 事务边界适配策略
- 业务逻辑错误应触发事务回滚，释放已占用的资源（如预扣库存）
- 在Saga事务模式中，业务逻辑错误应触发补偿事务（Compensating Transaction）
- 错误响应中应包含业务错误码和可读的错误描述，便于客户端处理
- 对于幂等校验发现的重复操作，应返回成功状态而非错误，保证接口幂等
// 业务逻辑错误响应示例（JSON）
{
"code": "INSUFFICIENT_BALANCE",
"message": "账户余额不足，当前余额：10.00，需要金额：100.00",
"details": {
"accountId": "acc_123456",
"currentBalance": 10.00,
"requiredAmount": 100.00
},
"traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}4.5 基础设施错误
基础设施错误发生在网络、中间件、硬件或底层平台层面，通常表现为连接超时、连接重置、DNS解析失败、磁盘I/O错误等。这类错误在事务边界中的核心特征是：不可预测且影响范围广，需要熔断和降级机制。
4.5.1 常见基础设施错误类型
| 错误类型 | 表现形式 | 典型原因 |
|---|---|---|
| 网络超时 | 连接超时、读取超时 | 网络延迟、带宽瓶颈 |
| 连接重置 | Connection Reset | 服务端异常关闭连接、防火墙拦截 |
| DNS解析失败 | Name Not Resolved | DNS服务器故障、域名配置错误 |
| 中间件故障 | Redis/MQ连接异常 | 中间件宕机、集群脑裂 |
| 磁盘/存储故障 | I/O Error | 磁盘损坏、存储节点离线 |
4.5.2 事务边界适配策略
- 基础设施错误应触发熔断器（Circuit Breaker），防止级联故障
- 事务应具备降级能力：在基础设施不可用时返回降级结果或缓存数据
- 对于关键事务，应实现多活部署或跨区域容灾
- 基础设施错误通常无法通过重试解决，需等待运维恢复
- 在事务日志中记录基础设施错误的上下文，便于根因分析
注意：基础设施错误与5xx服务端错误的区别在于：5xx错误通常服务端进程仍在运行，只是处理请求时发生异常；而基础设施错误意味着服务端进程可能已不可达或底层依赖已失效。两者的重试策略和熔断阈值应分别配置。
4.6 错误分类与事务边界的关系
下图展示了四类错误在API事务边界中的位置及其对事务状态的影响路径：
4.7 错误分类在移植适配中的实践要点
当将错误处理策略从一个系统移植适配到另一个系统时，需要关注以下要点：
- 错误映射一致性：确保源系统和目标系统的错误分类标准一致，避免将服务端错误误判为客户端错误
- 事务边界对齐：不同系统的事务边界可能不同，错误处理策略需根据新边界重新调整重试和补偿逻辑
- 幂等性迁移：服务端错误的重试依赖幂等性，移植时需确保目标系统已实现幂等校验
- 熔断阈值适配：基础设施错误的熔断阈值需根据目标系统的SLA和容灾能力重新配置
- 错误码标准化：业务逻辑错误的自定义码应在移植过程中统一，避免歧义
移植适配检查清单：
- ☐ 确认4xx错误不会触发自动重试
- ☐ 确认5xx错误已配置指数退避和最大重试次数
- ☐ 确认业务逻辑错误有对应的补偿接口
- ☐ 确认基础设施错误已集成熔断器
- ☐ 确认错误响应格式在源系统和目标系统之间兼容