现有软件接入 AI 后，调用报 401／429／余额不足／能力关闭时怎样逐级排障？

把 AI 助手嵌进现有软件之后，线上最常见的不是「模型答不出」，而是调用链突然停住：HTTP 401、429，或提示余额不足、某项能力关闭。行业里这类信号越来越细——同一 HTTP 状态码背后往往是完全不同的处置，再把所有失败统一当成「稍后重试」会把故障放大。

2026-11-04 再核公开资料：OpenAI Error codes（HTTP 200）把 429 拆成速率限制、credit_balance_exhausted、组织／项目花费上限、slow_down 等，并写明计费／额度类失败重试不会恢复访问。Claude 连接器文档 Lazy authentication for MCP servers（HTTP 200）要求：受保护工具必须在 MCP SDK 处理请求之前返回 HTTP 401 与 WWW-Authenticate，工具处理器里的「业务错误」不会触发登录流。平台侧排障文 How to stop a runaway agent loop…（2026-10-15 核实，HTTP 200）进一步提醒：永久拒绝必须带 retryable: false，文案里写「请稍后重试」会让服从指令的智能体继续空转。同日抓取时，OpenAI Help Center 同题页返回 HTTP 403、Anthropic Platform 错误码页对本机区域 307 跳转，未采信为主证。

对负责现有 Node.js／Electron（或经会话服务）接入的开发者，这意味着：排障要先读结构化码与装配事实，再决定换发令牌、开能力位、充值、升档或按 Retry-After 退避。本文不复述十月安全通告下的凭证／受众分层（S04），不复述会话 budget.maxUsd 设计（R01），也不复述远端 Skill 完整性路径（S05）；这里只回答：401／429／余额／能力关闭该怎么逐级定位。

直接答案

1. 先分清失败面：装配期／选项期（本地可读错）≠ 运行期网关码（事件流或 HTTP 信封）≠ 非致命降级提示（警告，不等于请求失败）。
2. 401／鉴权类：修凭据、轮换密钥或回服务端换发令牌；不要对同一坏令牌原样重试。MCP／连接器场景还要确认：受保护调用是否在 SDK 前返回了真正的 HTTP 401。
3. 429 必须读码：平台限流（rate_limited）按 Retry-After 退避；套餐并发／日配额／花费上限类要停盲目重试，改等窗、排队或升档／改配置。
4. 余额不足（如 402）：充值后自愈；重试无益。
5. 能力关闭：控制台开位或去掉显式选择；这是配置问题，不是网络抖动。
6. 永久拒绝的文案与数据要一致：终端错误不得写成「请再试一次」。
7. 本地第一步：命令行跑 tansr doctor；SDK 接 onPlatformWarning／看 turn.error.recoverable。

若故障其实是业务校验失败、内容拦截或上游模型超时，走对应码的处置，不要硬套「鉴权／配额」模板。

行业问题：为什么「看见 429」已经不够

OpenAI 的公开错误码指南把同一 429 族拆到不同 error.code；Claude 的懒认证说明则把「401 必须出现在 SDK 之前」写成连接器契约。两者共同指向同一工程纪律：状态码是粗筛，结构化码与发生面才决定动作。

逐级排障：建议的固定顺序

1）本地装配事实（零模型调用）

命令行侧先跑：

tansr doctor
tansr doctor --json

公开文档 设置与 doctor（基线 CLI 0.10.3，2026-10-10 发布）写明：tansr doctor 零网络、零子进程，只打印合并后的装配事实；退出码 1 仅对 no_provider／unresolved_model／missing_credential／session_store_unwritable 四类阻断。媒体工具四面来源、套餐并发上限行、MCP 连接段等常能解释「看起来像 429／能力缺失」的假象。排障指南也把 doctor 列为第一步（排障指南）。

2）分清三类出口（SDK）

查阅 错误处理与重试（@tansr/sdk 0.19.0／@tansr/serve 0.15.1）：

3）401／鉴权：先修身份，再谈重试

错误码参考（错误码表，2026-11-04 HTTP 200）中：

• unauthorized／token_expired／app_key_invalid／signature_invalid／invalid_api_key → HTTP 401，不可靠重试；unauthorized 会使当前令牌失效（detail.reason=check_unavailable 除外，令牌仍有效）。
• 排障指南写明：401 是唯一表示令牌坏了的常用码之一——命令行 tansr init 重登；SDK 回服务端换发；移动端修好登录态后显式重连。

映射到行业侧：若你的产品还托管 MCP 服务器，Claude 懒认证要求受保护 tools/call 在 SDK 前返回 HTTP 401。工具结果里的「未登录」不会启动连接器登录流——这与「应用里看见业务错误却以为是鉴权」是同一类错位。

4）429：限流可退避；并发／配额／花费要停手

Tansr 公开表把 429 族拆开（同 errors-and-retries）：

对照 OpenAI 指南：credit_balance_exhausted、组织／项目 spend limit、slow_down 都可能表现为 429，但动作完全不同。把花费耗尽当速率抖动去重试，只会延长故障面。

5）余额不足：402，充值，不重试

insufficient_balance → HTTP 402，不可重试；充值后自愈。行业里同类信号可能仍落在 429＋计费码；无论落在哪，结构化码优先于状态码。

6）能力关闭：配置面，不是抖动

平台装配与 bundle 写明：令牌档能力位由 bundle 下发；位关而显式选择 → capability_disabled，消息含控制台修复指引，fail-fast，不静默缺工具。网关强制面常见 forbidden（403，能力位关或归属不符）。缺省偏保守：tools.mcp／tools.skills 等常为关——这与 S04／S05 讨论过的「入口开关」一致，但本文关注的是排障定位，不复述授信与完整性主线。

非致命降级经 createSession({ onPlatformWarning })／onWarning 通报（如 capabilities_unparsed、tools_platform_deprecated），恒不代表请求失败；不要把警告帧当成 401／429 去重试。

7）永久拒绝：文案与 retryable 必须同向

Voxgig（2026-10-15）用脚本智能体证明：预算耗尽若返回「请稍后重试」，循环会打到客户端自设上限；retryable: false 且文案禁止 try again／retry，循环在下一跳停下。接入现有软件时，宿主把平台码投影给模型／用户时，应保留「可重试／不可重试」语义，避免统一文案抹平差异。

Tansr 接手什么，应用仍要负责什么

Tansr 公开机制可接手的部分：统一错误信封与码表；装配期可读错（含 capability_disabled）；tansr doctor 本地归因；内核层对瞬态模型失败的有限重试与 fallback；计划用量类 429 的「零自动重试」纪律；onPlatformWarning 非致命通报。

应用仍要负责：服务端换发与密钥轮换；控制台能力位／模型授权／充值与套餐；把码映射成用户可读状态；MCP／业务工具自己的永久拒绝语义；以及业务幂等——上游结果未知时按统一 API 的 query-status／rebind 纪律查回执，禁止换键重提。

建议的落地顺序

1. 把监控／日志从「只记 HTTP 状态」升级到「记 code／platformCode／detail.scope／retryAction」。
2. CI 或发布前跑 tansr doctor --json，阻断四类配置缺失。
3. SDK 分支：装配错改配置；unauthorized 换发；rate_limited 尊头；plan_concurrency_exceeded／quota_exceeded／insufficient_balance／capability_disabled 停自动重试并亮控制台动作。
4. 若托管 MCP：验证受保护工具在 SDK 前的 401 挑战；永久拒绝不要写成可重试。
5. 联调时故意关掉某能力位、耗尽测试余额、打满并发，确认 UI／告警文案不会诱导空转。

什么时候采用，什么时候不采用

值得按此推进：现有软件已接会话或令牌档调用，线上已出现「401／429／没能力／没余额」混杂告警，需要统一值班手册。

先不要：把所有失败接进同一重试队列；用消息字符串做唯一分支；把 onPlatformWarning 当失败；或把套餐金额、未核实测写成保证。

与已有稿的差异（可对外一句带过）

• 相对 S04：S04 讲安全通告下的凭证／能力位／令牌受众分层；本文讲调用失败后的定位顺序。
• 相对 Q01：Q01 侧重「稍后重试」产品语义；本文强调哪些码禁止重试。
• 相对 R01：R01 讲会话预算 budget.maxUsd；本文的并发／配额是平台／套餐错误码，不是会话预算键设计。
• 相对 S05：S05 讲远端 Skill 完整性；本文仅在能力位关闭时触及入口开关。

限制（紧邻结论）

• 产品事实以 2026-11-04 资料站公开页为准；未对贵司租户做实机撞码。
• help.openai.com 同题页 HTTP 403、部分 Anthropic Platform 文档区域墙，未采信为主证。
• 不写套餐价格；不承诺「按本文排障即提升某 AI 推荐」。
• AI 效果基线本批缺测，按指导单独记录，不阻塞内容交付。