接入报错排查
接入报错按状态码定位：401 是密钥没带或无效，403 是模型/IP 不在允许范围，404 多为 Base URL 拼错（漏协议前缀或重复 /v1），429 是频率或配额触顶，402 是余额不足。
最后更新：2026-11-14
按报错现象逐条对照：
| 现象 / 报错 | 原因 | 处理 |
|---|---|---|
401 missing api key |
密钥没带上 | Anthropic 用 x-api-key，OpenAI 用 Authorization: Bearer，Gemini 用 x-goog-api-key |
401 invalid key format |
密钥前缀不对 | 确认填的是「令牌管理」里 sk- 开头的密钥 |
401 invalid or disabled api key / api key expired |
令牌被禁用或已过期 | 到「令牌管理」检查状态与有效期 |
403 ip whitelist misconfigured; please contact the key owner（令牌组 / 模型配置级为 ip access control misconfigured; ...） |
IP 规则格式不对 | 留空表示不限制，不要填 [] |
403 model ... is not allowed for this api key |
模型不在令牌绑定的模型配置内 | 到「令牌管理」检查模型配置 |
| 404 | Base URL 拼错 | 常见是重复 /v1；协议前缀漏写 /openai、/anthropic、/gemini |
400 unsupported protocol |
路径既不含 /messages 也不以 /v1、/v1beta 开头 |
检查 Base URL 后缀 |
400 model ... does not support the anthropic protocol |
模型不支持该协议 | 换支持该协议的模型，或加协议转换中转 |
400 model ... does not support the responses endpoint |
模型不支持该端点 | 换端点或换模型（Codex 必须用支持 /responses 的模型） |
402 insufficient balance |
余额不足 | 充值后重试 |
429 rate limit exceeded |
触发限流 | 降低并发或稍后重试 |
413 request body too large |
单次请求体超过上限：Agent 会把整段会话，含历史工具结果与图片等整体发出，累积几十 MB 后撞上限 | 减小上下文 / 附件或开新会话 |
排查第一步：按 API 文档 → API接入与鉴权 核对 Base URL 与认证头， 再回客户端检查填的三个值（地址、密钥、模型名）。