先给结论
OpenAI / Claude API 出现 401 或 429，不要第一反应就是“这个 key 坏了”。更稳的顺序是：
| 错误 | 先判断什么 | 常见处理 |
|---|---|---|
| 401 | key 是否正确、是否过期、项目/组织是否匹配、权限是否足够 | 修 header / 环境变量 / project / 子 key 权限 |
| 429 · rate limit | 请求是不是太快、并发是不是太高、token 是不是太大 | 降并发、做退避重试、拆批、缓存 |
| 429 · quota / billing | 余额、月度上限或预付额度是否耗尽 | 补额度、调高限额、换计费档 |
| model not found / permission | 模型名、模型权限、路由目标是否匹配 | 换模型名、开权限、修网关路由 |
| timeout / overloaded | 请求太长、模型负载、网络或网关超时 | 开 streaming、缩短上下文、重试、查状态页 |
如果你走的是 AIRelay API Credit，还要多查一层：项目子 key、余额、项目限额、模型范围和 base URL 是否匹配。
第一步：先保存 8 个字段
不要把完整 API key、cookie、session 或验证码发给任何人。排障只需要这些脱敏字段：
| 字段 | 示例 |
|---|---|
| Provider | OpenAI / Claude / AIRelay / 其它网关 |
| Base URL | 只保留域名和路径，不带 key |
| SDK / 工具 | openai sdk / anthropic sdk / Claude Code / curl |
| 模型名 | gpt-4.1 / o 系列 / claude-sonnet-* |
| HTTP status | 401 / 429 / 404 / 500 |
| error type / message | authentication_error / rate_limit_error / insufficient_quota |
| request_id | OpenAI 或 Anthropic 返回的请求 ID，如有 |
| 时间和并发 | 发生时间、每分钟请求数、输入/输出 token 粗估 |
没有这些字段，排障很容易变成“换个 key 试试”。这对生产系统没有价值。
401：认证、组织、项目、权限
OpenAI 的官方错误码页把 401 放在 invalid authentication、incorrect API key、organization membership 等场景里；OpenAI API 参考也把 API key 当作 secret 处理。Anthropic 的错误页中，401 对应 authentication_error，意思是 API key 或认证信息有问题。
优先检查：
- Header 是否对。OpenAI-compatible 通常是 Authorization Bearer；Anthropic 直连通常使用对应的 Anthropic key / version 配置；走网关时按网关文档配置。
- 环境变量是否读到了旧 key。本地 shell、CI、Docker、Vercel、pm2 经常读到不同环境。
- key 是否属于正确组织、project 或 workspace。
- 子 key 是否被停用、过期、限额归零。
- 模型权限是否在这个 project / key 上开放。
- base URL 和 key 类型是否匹配。OpenAI key 打到 Anthropic 端点，或 AIRelay 子 key 打到官方端点，都会失败。
AIRelay 场景下，客户侧拿到的是项目子 key，不是上游原始 API key。401 要先查：
- 子 key 是否复制完整。
- 子 key 所属项目是否启用。
- 项目余额是否为 0。
- 项目是否允许当前模型。
- base URL 是否指向 AIRelay。
429：先分“额度耗尽”和“请求太快”
429 不是一个问题。至少要分两类。
第一类是额度 / 账单问题。OpenAI 错误码页把 exceeded quota 和 billing details 归到这类；这通常意味着余额、预付 credits 或月度上限不够。
第二类是限流问题。OpenAI rate limits 文档说明限流会按请求数、token、图片或音频等维度计算，并且通常在组织和项目层级生效。Anthropic rate limits 文档也把 Messages API 的限制拆成 RPM、ITPM、OTPM，并指出超过限制会返回 429 和 retry-after。
判断顺序：
| 现象 | 更像什么 | 下一步 |
|---|---|---|
| 刚开始就 429，余额页显示不足 | 额度 / 账单 | 补额度或调上限 |
| 小请求能跑，大批量就 429 | RPM / TPM / ITPM / OTPM 限流 | 降并发、拆批、退避 |
| 平时正常，突然放量后 429 | acceleration / 突增限制 | 放慢爬坡，保持稳定流量 |
| 同一模型 429，换低阶模型正常 | 模型级限流 | 调模型或申请更高限额 |
| 只有某个项目 429 | 项目限额 | 查 project / subkey 限额 |
Claude Code 走 gateway 时怎么查
Claude Code 官方 gateway 文档关注的是把 Claude Code 接到 LLM gateway：包括 gateway requirements、authentication configuration、model selection 和 endpoint setup。这里最容易错的是三件事：
- base URL 还是官方端点，但 key 已经换成网关 key。
- 只改了 base URL，没有改认证 token 或模型映射。
- 模型名在 Claude Code、网关和上游之间没有映射一致。
如果你使用 AIRelay 或其它网关跑 Claude Code，先写清：
| 字段 | 为什么重要 |
|---|---|
| base URL | 判断请求到底打到官方还是网关 |
| auth token 类型 | 判断用的是官方 key、网关 key 还是项目子 key |
| model alias | 判断模型名是否被网关映射 |
| workspace / project | 判断限额属于哪个项目 |
| request_id / gateway trace id | 让服务方能查日志 |
什么时候该联系服务方
可以自己先做三件事：
- 401：重新加载环境变量，确认 key、base URL、project 和模型权限。
- 429：把并发减半，加入指数退避，缩短上下文，看是否恢复。
- timeout：改 streaming，缩短 prompt，检查网络和上游状态。
需要服务方排查的情况：
- AIRelay 子 key 显示有余额但仍 401。
- 某个模型在后台显示可用，但请求返回 permission / model not found。
- 日志里有 request_id，但客户侧无法判断是上游、网关还是项目限额。
- 429 无法判断是余额、项目限额、模型限额还是突增限制。
联系时只发脱敏字段。不要发完整 API key、cookie、session、验证码、身份证件或银行卡。
AIRelay 的承接方式
AIRelay 更适合这些场景：
- 你需要人民币充值和项目子 key。
- 你要给多个项目或客户拆额度。
- 你需要用量账单和错误码排查。
- 你想把 Claude Code、OpenAI-compatible SDK 或 Agent 项目统一接到一个网关。
如果你只是要买一串来路不明 key，先读 API key vs API Credit。如果你已经要接入，读 API Credit 合规说明 和 价格说明。预算不确定时，先用 API Credit 用量估算器 算 ¥99 / ¥999 / ¥3000 在你的 token 规模下大概能跑多久。
如果你已经遇到报错，可以直接在 卡点自查 里选择「OpenAI / 海外 API」或「API key / 中转边界」，填入这 8 个脱敏字段。不要发送完整 API key、cookie、session、验证码或客户数据。