「exceeded retry limit」同一句报错三种病

「exceeded retry limit」是 AI 编程工具 Codex 里出镜率很高的一句报错，也最容易让人懵：它没说网络坏了、没说额度没了、也没说登录失效，只说重试到头了。原因是这句报错来自客户端的一层包装：请求失败后自动重试若干次，次数用尽就抛出这句话——至于最初失败的原因，被包在了里面。同一句话底下，压着 429、401、503 三种完全不同的病，治法各不相同。这篇讲清 wrapper 的包装机制、怎么从报错末尾的状态码分流，以及一条照着走的排查顺序；排障的核心动作是「先分流、再动手」，顺序反了全是在错误方向上使劲。

wrapper 的机制：重试到头才报这句

先拆包装层。客户端向服务端发请求，遇到可重试的失败会自动再试，重试若干次仍失败，才把「exceeded retry limit」抛给你。这个设计对瞬时抖动是友好的——多数小故障在自动重试里就消化了，你根本看不见；但它有个副作用：报错文案不携带根因，三次失败可能是三种不同原因，报错只有同一句。根因藏在哪？在完整报错的末尾：包装层通常把最后一次失败的原始状态码一并打出来，429、401 或 503——那才是真正的病历。所以看到这句报错，第一个动作是往上翻完整日志找末尾的数字，别盯着 wrapper 那句话研究；终端里报错被截断时，把窗口拉宽或翻历史输出，信息都在。

看末尾状态码分流：429、401、503

三个状态码对应三条道。429 是限流或额度侧的信号：可能是真超额，也可能是误报，先跑 /usage 核对余量再定，分流方法见429 误报一篇。401 是凭据侧的信号：登录态过期或认证信息出问题，处理是 codex logout && login 重新走一遍登录，凭据文件的机制与更多细节见401 处理一篇。503 是服务端侧的信号：服务在降级或过载，本地无解，等状态页公告，判断方法见503 处理一篇。三条道的共同点是都不是这句报错本身的问题——wrapper 只是信使，要治的是它后面那个人。

排查顺序：三查定方向

按顺序走，别跳步：

• 第一步，翻完整报错找末尾状态码：有 429、401 或 503，按上节三条道分流，各自走对应的排查。
• 第二步，没有状态码时看连接层线索：报错里出现 stream disconnected before completion 或类似措辞，方向转向网络与代理——长连接被掐断后重试耗尽，同样会包装成这句话，排查见流断连一篇。
• 第三步，全部无效后升级 CLI 再试：重试行为跨版本有过变化，截至发稿版本，以官方更新日志为准；升级后仍复现，带着完整日志到社区 issue 检索。

三步走完，绝大多数场景能落到三条道之一或连接层；还没方向的，说明手里的信息不够，把完整报错原文留存下来再求助，比反复盲试有效。

重试的正确姿势与边界

wrapper 的自动重试是给你的第一道缓冲，但它本身不是修复：429 之下干等重试、503 之下连环手点，都只是在放大问题。手动重试的纪律是拉间隔：第一次失败后等几十秒再试，仍失败翻倍再等，指数退避的通用思路见工具重试一篇——API 调用场景里这已是成熟实践，交互式使用同理。还要分清「该等」与「该修」：503 与已知事故期属于该等，401 与本地网络问题属于该修，429 先查再定。让这套分流变成条件反射，可以让 DeepSeek 把 429、401、503 三条道整理成一张分流卡，再用豆包模拟三个状态码的报错场景，对照卡片口头各走一遍排查顺序，真遇到报错就不会慌。

retry limit 速查

• 这句报错是重试耗尽的包装，根因在末尾的原始状态码
• 429 查额度与误报，401 重登录，503 等状态页
• 无状态码时查连接层：流被掐断同样包装成这句
• 手动重试拉间隔、指数退避，别连环硬点
• 跨版本重试行为有差异，以官方更新日志为准

关于 retry limit 报错的常见疑问

• 为什么同一句话，每次的原因都不一样？：wrapper 只报告「重试到头」，不报告为什么失败；末尾状态码才是根因，三次报错三次码完全正常，每次都按分流重新判断，别套用上次的结论。
• 重试次数能调大吗？：可调参数以当前版本文档为准；但调大次数治标不治本，429 之下重试越密越挤，先分流根因再谈参数，多数情况下根因解决后默认次数足够。
• 末尾连状态码都没有怎么办？：先按连接层排查——网络、代理、超时逐项过，再升级 CLI 拿更完整的报错输出；两步之后仍无信息，带完整日志到社区 issue 检索同类案例。