公开数据接口调用失败:按错误码决定重试还是改请求
调用失败先别急着加次数。本文按错误码把失败分成可重试、需改参数、需改调用方式三类,给出重试节奏与停止条件,减少无效重试,并说明以官方最新说明为准。

遇到公开数据接口调用失败,先看错误码,再决定动作:属于临时性故障的,退避后重试;属于请求本身有问题的,改参数或改调用方式,重试多少次都不会变好。把这两类分开,是减少无效重试最直接的一步。下面按错误码的分类、重试的节奏、停止的条件三块讲,具体码值以接口方文档为准。
先分清三类失败
公开数据接口的错误码,各家的编号不统一,但按成因大体能归成三类。判断方法不是背码值,而是看文档里每个码对应的说明,再问一句:同样的请求原样再发一次,有没有可能成功。
- 临时性失败:限流、服务繁忙、网关超时、上游暂时不可用。同样的请求过一会儿再发,有可能成功,这类才值得重试。
- 请求本身有问题:参数缺失、参数类型不对、时间范围超限、分页越界、鉴权信息过期或错误。原样重发结果一样,要先改请求。
- 调用方式有问题:请求频率长期超过配额、单次拉取量过大、并发开得太高。改重试次数没用,要改的是调用节奏和单次请求的规模。
第三类容易被误当成第一类。限流返回的码看起来像临时故障,但如果每次重试都立刻再撞上限流,说明问题在调用节奏,不在运气。
哪些该重试,哪些该改参数
把常见情形列成一张对照表,方便接接口时先自查。码值一列留空,按你所用接口的文档填。
情形 典型表现 该做什么 不建议做什么 限流 短时间大量请求后被拒 降低频率,按响应头或文档给的等待时间退避 原地立刻重发 服务端临时故障 5xx 类状态,偶发 指数退避重试,设上限 无限重试 参数错误 4xx 类中提示字段问题 对照文档改字段名、类型、取值范围 重试 鉴权失效 提示令牌过期或无权限 重新获取凭证,检查权限范围 反复用旧凭证重试 分页越界 请求的页码或偏移超出总量 按返回的总数收敛循环条件 继续往后翻 超时 连接或读取超时 适当延长超时,缩小单次数据量后重试 一味加大超时表里最需要留意的是 4xx 和 5xx 的分界。多数接口把客户端错误放在 4xx,把服务端问题放在 5xx,但这不是所有接口都严格照办,判断仍以文档说明为准。
重试的节奏怎么定
确定要重试之后,节奏比次数更重要。几个做法可以直接用。
第一,用退避而不是固定间隔。第一次失败等一两秒,之后每次把等待时间拉长,比如翻倍,直到上限。固定间隔重试在限流场景下容易持续撞墙。
第二,给重试设总次数和总时长两个上限。只设次数不设时长,遇到慢响应会拖很久;只设时长不设次数,间隔太短时次数会很多。两个都设,取先到的那个停。
第三,重试前判断错误是否可重试,别把整个请求无差别再发一遍。伪代码大致是这样:
for attempt in 1..max_attempts:
resp = call_api(params)
if resp.ok: break
if not retryable(resp.code): raise
sleep(backoff(attempt))
retryable 这个判断函数,就是把上一节表格里「该做什么」为改参数、改凭证的情形排除掉。
第四,注意幂等。查询类接口重复调用一般没有副作用,重试相对安全;如果接口带有写入或计费性质,重试前要确认重复提交不会造成重复记录或重复扣费,视情况而定。
什么时候该停
无效重试的代价不只是浪费时间,还会把限流窗口占满,让正常请求也失败。几个停止信号值得记住。
- 同一个错误码连续出现多次,且属于参数或鉴权类,立刻停,去改请求。
- 重试次数或总时长到达上限,停,记录下错误码和请求参数,转人工排查。
- 限流类错误在退避后仍然连续出现,说明配额或频率设置本身有问题,停,先降频或错峰。
- 错误码在同一批请求里高度集中,往往指向请求构造的共性问题,而不是偶发故障。
停下来之后要做的事,是把失败请求的关键信息留档:时间、错误码、请求参数摘要、重试次数。没有这些,事后很难判断是接口侧波动还是自己这边的问题。
把判断写进调用代码
上面这些如果只停留在文档里,接接口的人还是会凭感觉重试。比较稳妥的做法是把分类写进代码:维护一张错误码到处理动作的映射,重试逻辑只认这张表,遇到表里没有的码,默认不重试并记录。新增码值时补表,而不是临时在调用处加判断。
另外,把重试次数和最终失败率记下来,能看出重试有没有起作用。如果重试很多但成功率没变化,多半是分类错了,把该改参数的请求拿去重试了。
平台规则、错误码含义、配额和限流策略都可能调整,本文不列具体条款和数值,实际接入时以接口方官方最新说明为准。
本文由 AI 生成
本文由极媒数据发布。转载请注明出处并保留原文链接。
留下联系方式,免费获取数据方案与报价