裸 429 先看响应头

Claude Code 通过 OAuth 调用高级模型时,如果返回的 429 没有 Retry-After,也没有 anthropic-ratelimit-unified-* 头,不能直接判断为额度耗尽。一个 2026-08-17 的公开复现显示,缺少正确的 Claude Code system 标记会触发订阅 entitlement gate,响应体只剩下 rate_limit_error 和 message: Error。

真正的限流通常会带有重试时间或额度相关的响应信息。裸 429 更像请求没有通过模型访问资格检查。

用最小请求区分两种 429

先使用隔离测试账号和短请求,不要把真实 OAuth token 粘贴到聊天或 issue。只比较三组请求的状态码和响应头:

Text
请求 A:高级模型,不带 system block
请求 B:高级模型,Claude Code system block 放在第一段
请求 C:Haiku 模型,不带 system block

公开复现中,A 返回无头 429,B 返回 200 和统一限流头,C 返回 200。这组对照可以把“权限门槛”和“服务端拥塞”分开。

为什么 system block 的位置会影响结果

问题报告指出,检查器要求第一段 system 内容包含 Claude Code 的标识文本;同样的文本放在第二个 system block 中,仍然会被拒绝。对直接调用 Anthropic Messages API 的网关、代理和 SDK 来说,这意味着消息重排可能改变权限结果。

如果你通过自建网关或第三方编排器调用订阅 OAuth,检查它是否:

  • 合并或重排了 system blocks
  • 在重试时丢掉了第一段 system 内容
  • 把 Claude Code 请求改写成普通 API 请求
  • 用“429 就降并发”的策略处理所有 429

失败时不要先扩大额度或循环重试

看到裸 429 时,先暂停自动重试,保存状态码、响应头名称和脱敏后的消息结构。扩大并发、切换 IP 或等待几分钟,无法修复 entitlement gate;反而可能让编排器把健康账号误判为限流。

如果必须临时恢复工作流,先切到账号明确可用的模型,并确认新请求仍由 Claude Code 正常发出。不要伪造 system 标识来绕过供应商权限策略。

修复后的成功标准

成功标准包括:

  1. 高级模型请求返回 200,或返回带 Retry-After 的真实限流响应。
  2. system block 顺序在代理前后保持一致。
  3. 网关不会把裸 429 无限重试或误记为额度耗尽。
  4. 账号、模型和请求入口的权限关系能在日志中解释清楚。

如果只有第三方编排器失败,而 Claude Code 官方路径正常,优先修复消息构造和路由层,不要继续修改 API Key。

参考来源

OAuth Max 20x: bare 429 rate_limit_error on premium modelsGitHub IssueClaude Code ReleasesAnthropic GitHub

相关文章

Claude Code 认证失败:401 unauthorized / invalid x-api-key 怎么排查错误日志 / 约 12 分钟Claude Code model not found 怎么排查:入口、Key 和模型映射错误日志 / 约 12 分钟Claude Code 登录订阅后仍走 API Key 怎么排查错误日志 / 约 10 分钟Claude Code 接入 DeepSeek API:配置方法和报错处理智能编程 / 约 24 分钟

作者信息