常见报错与排障指引 (FAQ)

调用 API 或在客户端配置遇到问题时，请先对照以下常见错误清单进行排查。

---

1. 错误代码排查手册

401 Unauthorized（未授权）

• 原因 1：API Key 复制有误（带了前后多余空格或换行）。
• 原因 2：Header 格式写错。OpenAI 协议必须是 Authorization: Bearer sk-...；Anthropic 协议是 x-api-key: sk-...。
• 原因 3：Key 已在控制台被手动禁用或删除。

---

403 Forbidden（权限拒绝）

• 原因 1：ClaudeMax 分组被普通客户端调用。ClaudeMax 分组严格限定为官方 Claude Code 终端，若在 Cursor、NextChat 或普通脚本中调用会被网关 403 拦截。
  • 解决办法：请在控制台另建一把绑定 Kiro按量计费 或 Kiro按次计费 的 Key。
• 原因 2：非 GPT 分组调用生图接口。若使用 Claude 或 DeepSeek 分组 Key 访问 /v1/images/generations，会被拒绝。
  • 解决办法：生图请使用绑定 GPT稳定池 或 GPT纯血Pro订阅 的 Key。

---

400 Model Not Supported（模型不支持）

• 原因 1：模型名称拼写错误。例如多打了空格或写了上游的原生别名。
  • 解决办法：调用 GET /v1/models 或查阅 现役全量模型目录 确认模型确切 ID。
• 原因 2：该 Key 所在分组未包含该模型。例如用 GPT 分组去调 claude-sonnet-5。
  • 解决办法：核对您所选分组支持的模型范围。

---

429 Too Many Requests（超出限额或并发）

• 原因 1：账户余额耗尽。请前往控制台充值。
• 原因 2：短时间内触发了单 IP 或单 Key 的突发高频保护。稍等几秒或在代码中引入指数退避重试（Exponential Backoff）。

---

请求超时或断开连接（特别是长思考/推理模型）

• 现象：调用 deepseek-v4-pro 或复杂推理任务时，客户端等待 60s 或 100s 后报错 Connection timeout。
• 原因：深思考模型的思维链（Reasoning）生成可能持续 100~200 秒。如果客户端设置了默认 60s 超时，或者反向代理层开启了短超时，会导致连接被提前切断。
• 解决办法：
  1. 将客户端 HTTP 请求超时时间（Timeout）调大至 300 秒或 600 秒；
  2. 启用流式传输（stream: true），让服务端在思考时持续回传心跳 Token，保持 TCP 连接活跃。