先别急着换 key
API 报错看起来很像"钥匙打不开门"。401、403、429、model not found、timeout 混在一起，很容易最后都归成 key 坏了。线上排障别这么做，先按层拆开：
| 现象 | 更像哪一层 | 第一件事 |
|---|---|---|
| 401 / authentication_error | 认证层 | 查 key、header、base URL、项目归属 |
| 403 / permission_error | 权限或地区层 | 查模型权限、项目权限、服务支持地区 |
| 429 rate limit | 限流层 | 查 RPM / TPM / ITPM / OTPM、并发、retry-after |
| 429 quota / billing | 余额或账单层 | 查余额、月度上限、项目限额 |
| model not found | 模型路由层 | 查模型名、别名、网关映射 |
| timeout / 5xx | 网络或上游层 | 查状态页、重试策略、上下文大小 |
走 AIRelay API Credit 时，还要看一层网关侧信息：项目子 key、项目余额、模型范围、base URL、错误日志是否能对上。
先把 8 个字段留出来
不要把完整 API key、cookie、session、验证码、客户数据发给任何人。排障只需要这些字段：
| 字段 | 怎么填 |
|---|---|
| Provider | OpenAI / Claude / AIRelay / 其它网关 |
| Base URL | 只留域名和路径，不带 token |
| SDK / 工具 | openai sdk / anthropic sdk / Claude Code / curl |
| 模型名 | 请求里实际传入的 model |
| HTTP status | 401 / 403 / 429 / 500 |
| error type / message | 只贴错误类型和关键信息 |
| request_id / trace id | 有就保留，方便服务方查日志 |
| 时间和并发 | 发生时间、每分钟请求数、输入输出 token 粗估 |
没有这些字段，服务方只能陪你猜。猜到最后通常就是"换个 key 试试"，这对生产系统没什么价值。
401：先看 key 和端点有没有对上
OpenAI 官方错误码文档把 401 归到认证问题：API key 错误、认证信息无效、组织或项目不匹配。Anthropic 的错误文档里，401 对应 authentication_error。
按这个顺序查：
- Header 是否对。OpenAI-compatible 通常是
Authorization: Bearer；Anthropic 直连通常按 Anthropic API key / version 配置；走网关时按网关要求。 - 环境变量是否读到了旧 key。本地 shell、CI、Docker、Vercel、pm2 经常不是同一套环境。
- key 是否属于正确组织、project 或 workspace。
- 子 key 是否被停用、过期、限额归零。
- base URL 和 key 类型是否匹配。官方 key 打到网关端点，或网关 key 打到官方端点，都会失败。
AIRelay 场景下，客户侧拿到的是项目子 key。401 先查子 key 所属项目、余额、模型范围和 base URL。
403：权限、地区、模型范围分开看
OpenAI API 支持国家和地区是官方清单口径：如果某个地区不在清单内，API 不支持。OpenAI 错误码里也有 unsupported country / region / territory 的解释。Anthropic 侧也有 Claude 可访问地区清单和 API 支持边界。
所以 403 不一定是 key 错。它可能是：
- 这个 key 没有当前模型权限。
- 项目或组织没有启用某个资源。
- 请求来自不支持的地区或网络。
- 网关只开放了部分模型，模型名虽然看起来对，但路由没有权限。
工程上不要把 403 当成"多刷新几次就好"。先把权限、地区、模型路由拆开查。
429：看余额，也看请求节奏
OpenAI 官方错误码把 429 分成两类：请求太快导致 rate limit，或当前 quota / billing 不足。OpenAI rate limits 文档也明确说明限流是为了控制单位时间内请求和 token 使用。Anthropic rate limits 文档同样把 429 和 retry-after、请求数、输入/输出 token 等限制放在一起。
判断顺序：
| 现象 | 更像什么 | 下一步 |
|---|---|---|
| 刚开始就 429，控制台余额不足 | 额度 / 账单 | 补额度或调限额 |
| 小请求正常，大批量失败 | TPM / RPM 限流 | 降并发、拆批、退避 |
| 平时正常，突然放量后 429 | 突增限制 | 放慢爬坡，分批上线 |
| 同一模型 429，换低阶模型正常 | 模型级限流 | 调模型或申请更高限额 |
| 只有某个项目失败 | 项目限额 | 查 project / subkey 限额 |
自动重试要有上限。OpenAI 官方 SDK 会对部分 429 / 5xx 做默认重试，但生产系统不能只靠默认重试。至少要加指数退避、并发上限、请求队列和失败告警。
model not found：把三列写出来
这类问题在中转站和 Claude Code 网关里最常见。
常见原因：
- SDK 里写的是新模型名，但网关还没上架。
- 网关支持模型别名，但你传的是官方完整名。
- 项目子 key 限制了模型范围。
- OpenAI-compatible SDK 打到了 Anthropic Messages 格式端点。
- Claude Code 的 base URL 改了，但模型配置没有改。
这里别先换 key。把三列写出来：客户端传入的 model、网关识别的 model、上游实际路由的 model。三列对齐后，问题通常就能定位。
接到 AIRelay 时怎么处理
AIRelay API Credit 主要处理这几类需求：
- 你需要人民币充值和项目子 key。
- 你要给多个项目或客户拆额度。
- 你需要用量账单和错误码排查。
- 你想把 Claude Code、OpenAI-compatible SDK 或 Agent 项目统一接到一个网关。
已经在接入的话，先看 API Credit 合规说明、API Credit 用量估算器 和 OpenAI / Claude API 401 和 429 排障清单。遇到报错，把上面 8 个脱敏字段发到 卡点自查 或 加入社群，让真人按日志看。不要发送完整 key、cookie、session、验证码或客户数据。