一句话定义:调用接口失败时,先看错误码(error code)属于哪一类,再决定“退避重试、直接放弃还是先确认状态”,而不是一律重试、一律报错;这套约定就叫 API 错误码的分级处理。
用打电话来理解
想象你给同事打电话:
- 占线(对方忙):过一会儿再拨,而且越拨间隔越长——这对应 429 Too Many Requests,意思是“你请求太多了”,处理方式是退避重试(backoff),最好再加一点随机抖动(jitter),避免所有客户端在同一秒集体重拨;服务端如果返回
Retry-After响应头,就按它说的等。 - 号码拨错了:再拨一万次也没用——这对应 400 Bad Request、401 Unauthorized、403 Forbidden、404 Not Found、422 这类 4xx,是客户端这边请求本身有问题:参数格式不对、凭证过期、资源不存在。正确做法是改代码或改数据,重试只会白烧配额和钱。
- 对方说“我这会儿忙不过来”:可以等,但要看这通电话是不是“说三遍就会办三遍”的事——这对应 500、502、503、504 这类 5xx。能不能重试,取决于这次请求是否幂等(idempotency)。
幂等性是分级的关键
幂等是指同一个请求执行多次,结果和执行一次相同。查询(GET)、整体替换(PUT)、删除(DELETE)通常天然幂等,重试相对安全;而“创建订单”“扣减余额”这类 POST 请求不幂等,超时后盲目重试就可能重复下单、重复扣款。稳妥做法是带一个幂等键(idempotency key),或者失败后先查一次状态再决定。
| 错误码区间 | 谁的问题 | 推荐动作 |
|---|---|---|
| 429 | 你调得太快 | 指数退避 + 抖动,尊重 Retry-After |
| 400 / 401 / 403 / 404 / 422 | 请求本身有问题 | 不重试,修请求或修凭证 |
| 408 / 500 / 502 / 503 / 504 | 服务端或网络问题 | 幂等请求可退避重试,非幂等先查状态 |
| 重试若干次仍失败 | 已经不可用 | 熔断(circuit breaker)、降级、告警 |
与相邻概念的区别
很多人把“重试”“熔断”“限流”和错误码分级混为一谈。分级处理是判断依据:先根据错误码归类,再决定怎么处理;重试、熔断、降级是执行动作。没有分级的重试,本质上是把随机性当成策略。
对从业者的意义
最典型的故障放大路径是:上游返回 429 表示限流,下游 SDK 却对所有错误一律重试三次——瞬时流量变成三倍,限流迅速升级为全站不可用,一次小抖动滚成雪崩。分级处理的收益很直接:不该重试的错误立刻失败,该等的时候等得聪明;同时给重试设上限(次数和总时长),超过上限就熔断并向调用方明确报错。落到代码里通常就是一张“错误码 → 策略”的映射表,加上统一的重试封装。具体错误码语义以各服务商的官方文档页面为准。
