現有軟件接入 AI 後，如何逐級排查 401、429、餘額不足及能力關閉？

2026-11-04 7

版权

本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。

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

把 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／余额／能力关闭该怎么逐级定位。

直接答案

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

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

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

表象	常见误处置	应先问的问题
HTTP 401	立刻指数退避重试	是密钥错、令牌过期／吊销，还是受保护 MCP 工具根本没触发登录挑战？
HTTP 429	统一 sleep 再打	是速率、加速限制、日配额、套餐并发，还是花费／预付余额耗尽？
「没工具／能力不可用」	怪模型或怪网络	是能力位关了、装配期 `capability_disabled`，还是列表缓存过期？
「请稍后重试」文案	让智能体继续循环	结构化字段是否其实 `retryable: false`？

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）：

类	典型表现	处置原则
`TansrSdkError` 装配／选项期	如 `capability_disabled`、`invalid_options`、`assembly_failed`	重试无益；改代码或控制台配置
事件流	`turn.error`／`tool.failed`／`turn.aborted`	看 `recoverable`；`true` 多为咨询，会话可续
平台网关码	`unauthorized`、`rate_limited`、`insufficient_balance`…	按码表；计划用量类 429 SDK 零自动重试

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）：

码	处置
`rate_limited`	按 `Retry-After` 整秒等待；不要更密重发
`plan_concurrency_exceeded`	只拒新会话；运行中会话不断；零自动重试；约 30 秒后手动再发或升档
`quota_exceeded` 与各面 `*_quota_exceeded`	等配额窗；不要重试硬撞
`plan_end_users_exceeded`	测试期终端用户数触顶（铸令牌径）

对照 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 纪律查回执，禁止换键重提。

建议的落地顺序

把监控／日志从「只记 HTTP 状态」升级到「记 code／platformCode／detail.scope／retryAction」。
CI 或发布前跑 tansr doctor --json，阻断四类配置缺失。
SDK 分支：装配错改配置；unauthorized 换发；rate_limited 尊头；plan_concurrency_exceeded／quota_exceeded／insufficient_balance／capability_disabled 停自动重试并亮控制台动作。
若托管 MCP：验证受保护工具在 SDK 前的 401 挑战；永久拒绝不要写成可重试。
联调时故意关掉某能力位、耗尽测试余额、打满并发，确认 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 效果基线本批缺测，按指导单独记录，不阻塞内容交付。