#常见问题排查

排障建议按这个顺序来：先确认 Key，再确认 Base URL，再确认协议，最后确认模型和余额。不要一开始就怀疑模型不可用，大多数首次接入问题都是字段填错。

#30 秒快速定位

#推荐排障流程

1. 用在线调试台测试同一个 Key 和模型。
2. 如果在线调试台失败，回到认证与令牌检查 Key、余额、分组。
3. 如果在线调试台成功但客户端失败，检查客户端 Base URL 和协议。
4. 到控制台调用日志查看实际请求路径、模型名、HTTP 状态码。
5. 把复杂请求改成最小请求，只保留模型名和一句话 prompt。

排查问题时，重点看请求时间、令牌、模型、Tokens、费用和详情里的状态信息。对外发送截图前，请先打码 API Key、邮箱、余额和用户 ID。

#401：Invalid API key

#现象

客户端提示 Unauthorized、Invalid API key，或返回 HTTP 401。

#常见原因

• Key 少复制了一位。
• Key 前后带了空格。
• Key 填进了模型名、Base URL 或其他字段。
• 当前令牌已删除或被禁用。
• Windows PowerShell 和 WSL 设置了不同环境变量。

#处理方式

1. 回到控制台重新复制令牌。
2. 确认请求头是 Authorization: Bearer sk-...。
3. 如果是 Claude 客户端，确认 x-api-key 或 ANTHROPIC_AUTH_TOKEN 是否正确。
4. 用在线调试台验证同一个 Key。

#402：余额或额度不足

#现象

请求提示 insufficient quota、余额不足、quota exceeded。

#常见原因

• 账户余额不足。
• 单个令牌设置了额度上限。
• 当前分组有单独预算限制。

#处理方式

1. 到控制台查看钱包和消费记录。
2. 查看令牌额度是否耗尽。
3. 换一个测试令牌验证。
4. 给高频工具单独建令牌，避免和生产应用互相影响。

#404：model not found

#现象

模型不存在、Model not found、No such model，或客户端模型列表为空。

#常见原因

• 模型名拼写错误。
• 客户端没有手动添加自定义模型。
• 令牌分组无权访问该模型。
• 协议不匹配，例如用 Claude 协议请求 OpenAI Chat 模型。

#处理方式

1. 在控制台确认可用模型名。
2. 手动添加模型名，不依赖客户端自动拉取。
3. 换一个通用模型做最小测试。
4. 回到协议选择指南确认协议。

#404：路径不存在

#现象

返回 not found，但不是 model not found。

#常见原因

• Base URL 多写了 /v1，客户端又自动补了一次。
• Base URL 少写了 /v1，客户端又不会自动补。
• 手动把 /chat/completions 填进了 Base URL。

#处理方式

多数 OpenAI 兼容客户端填：

https://www.wanmoapi.com/v1

如果客户端会自动拼接 /v1，则填：

https://www.wanmoapi.com

判断方法：如果报错路径里出现 /v1/v1/...，说明你重复填写了 /v1。

#429：rate limited

#现象

请求偶发失败，或批量任务中部分请求返回 429。

#常见原因

• 客户端并发过高。
• 翻译插件一次性拆分太多段落。
• 令牌或分组设置了较低速率。
• 上游模型限流。

#处理方式

• 降低并发和每秒请求数。
• 为批处理任务增加重试和退避。
• 使用更适合高并发的模型或分组。
• 查看调用日志确认是否集中在某个时间段。

#400 / 422：请求格式错误

#现象

返回 invalid request、missing field、unsupported parameter 等。

#常见原因

• 客户端发送了模型不支持的参数。
• 使用了错误协议路径。
• JSON 请求体格式不正确。
• 把 Responses 请求发到了 Chat Completions。

#处理方式

1. 用本文档里的最小 curl 示例测试。
2. 去掉非必要参数，只保留 model、messages 或最小输入。
3. 确认路径是 /v1/chat/completions、/v1/responses 还是 /v1/messages。
4. 如果是客户端自动附加参数，尝试关闭高级参数或换兼容模型。

#流式响应卡住

#现象

客户端一直转圈、只输出一部分、或最后不结束。

#常见原因

• 客户端没有正确解析 SSE。
• 本地代理、Nginx 或 CDN 开启了响应缓冲。
• 请求超时太短。
• 模型返回时间较长，客户端误判超时。

#处理方式

• 先用非流式请求确认模型和 Key 可用。
• 确认请求中设置了 stream: true。
• 运维侧关闭 proxy_buffering。
• 增大 proxy_read_timeout。
• 换一个客户端验证是否是客户端解析问题。

#Codex / Claude Code / Cline 专项

#仍然无法定位

请保留这些信息，方便排查：

• 客户端名称和版本。
• 操作系统：Windows、macOS、Linux、WSL。
• Base URL 截图。
• 模型名。
• 控制台调用日志里的原始错误。
• 你用在线调试台测试同一个 Key 是否成功。

下一步：错误码对照 或 FAQ。