排错手册
按报错内容查原因和解决办法。
先做这个测试
先绕开客户端,直接测试密钥。这能判断问题出在密钥还是客户端配置上:
curl https://otokapi.com/v1/models \
-H "Authorization: Bearer sk-你的密钥"| 结果 | 说明 |
|---|---|
| 返回模型列表 | 密钥没问题,检查客户端的地址和模型名 |
| 返回 401 或 403 | 密钥或账号有问题,查下面的表 |
| 连接失败或超时 | 网络问题,见连不上 |
服务状态可以看 /health,各分组的可用率可以看渠道状态。
按报错查
401:密钥无效
| 报错 | 原因 | 解决办法 |
|---|---|---|
API_KEY_REQUIRED | 请求没带密钥 | 检查客户端有没有填密钥。Claude Code 用 ANTHROPIC_AUTH_TOKEN,Codex 用 auth.json |
INVALID_API_KEY | 密钥不对 | 重新复制,注意不要多空格、少字符。不能用官方的密钥 |
API_KEY_DISABLED | 密钥被停用 | 到 API 密钥页面启用,或新建一把 |
USER_INACTIVE | 账号不可用 | 联系客服 |
403:没有权限
| 报错 | 原因 | 解决办法 |
|---|---|---|
INSUFFICIENT_BALANCE | 余额不足 | 到控制台充值 |
API_KEY_EXPIRED | 密钥过期 | 延长有效期,或新建一把 |
ACCESS_DENIED | IP 不在密钥的允许范围内 | 修改密钥的 IP 限制 |
GROUP_NOT_ALLOWED | 这把密钥的专属分组你已不能使用 | 给密钥换一个分组 |
Image generation is not enabled for this group | 这个分组不能生图 | 用生图分组的密钥 |
404:地址或模型不对
| 报错 | 原因 | 解决办法 |
|---|---|---|
Model "xxx" is not available for this group | 分组里没有这个模型 | 换模型,或换分组,见怎么查模型 |
| 没有模型相关内容的 404 | 地址的 /v1 写错了 | 按这张表核对 |
Images API is not supported for this platform | 这个分组所属平台不支持生图接口 | 用生图分组的密钥 |
413:请求太大
Request body is too large 表示请求体超过了大小限制。常见原因是对话中带了大文件或大图,可以压缩后再发,或者开一个新会话。
429:请求太多或额度用完
| 报错 | 原因 | 解决办法 |
|---|---|---|
API key 额度已用完(API_KEY_QUOTA_EXHAUSTED) | 密钥达到你设置的总额度 | 到 API 密钥页面调整 |
API_KEY_RATE_5H_EXCEEDED、API_KEY_RATE_1D_EXCEEDED、API_KEY_RATE_7D_EXCEEDED | 密钥达到你设置的 5 小时、1 天或 7 天限额 | 等时间窗口过去,或调高限额 |
Concurrency limit exceeded | 同时发出的请求太多 | 降低并发,稍后重试 |
Too many pending requests | 排队的请求太多 | 降低并发,稍后重试 |
INVALID_AUTH_RATE_LIMITED | 短时间内多次使用错误的密钥 | 修正密钥,等一会儿再试 |
503:暂时没有可用渠道
No available accounts 或 Service temporarily unavailable 表示这个分组当前没有可用的上游渠道。可以稍后重试,或者看渠道状态,临时换一个分组。
请求约 2 分钟后断开
经过 Cloudflare 的连接,如果约 125 秒没有任何数据,就会被断开。非流式请求要等模型全部生成完才返回,复杂任务很容易超过这个时间。
| 接口 | 解决办法 |
|---|---|
/v1/responses、/v1/chat/completions | 使用流式(stream: true) |
Claude 分组的 /v1/messages | 不用处理,OpenToken 会自动保持连接 |
/v1/images/generations | 使用异步接口 |
连接断开后,上游可能仍在生成,这次请求可能照常计费。
连不上
如果 curl 也连接失败或超时,问题在你和 OpenToken 之间的网络上:
- 打开
/health,返回{"status":"ok"}就说明服务正常。 - 检查本机代理或 VPN 的规则,确认
otokapi.com能访问。 - 客户端如果不走系统代理,要单独设置环境变量。把端口换成你的代理端口:
export HTTPS_PROXY="http://127.0.0.1:端口"
export HTTP_PROXY="http://127.0.0.1:端口"还是解决不了
联系客服时,请提供报错原文、发生时间、使用的客户端和模型。不要发送完整的密钥。