跳到主内容
快讯直播
AI智模界
AI 词典

API 错误码的分级处理:别让一次失败滚成雪崩

一句话定义:调用接口失败时,先看错误码(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 却对所有错误一律重试三次——瞬时流量变成三倍,限流迅速升级为全站不可用,一次小抖动滚成雪崩。分级处理的收益很直接:不该重试的错误立刻失败,该等的时候等得聪明;同时给重试设上限(次数和总时长),超过上限就熔断并向调用方明确报错。落到代码里通常就是一张“错误码 → 策略”的映射表,加上统一的重试封装。具体错误码语义以各服务商的官方文档页面为准。

AI 生成本文由 AI 基于公开信息自动生成,仅供参考。