主题
常见问题
推荐排查顺序
- 检查账户余额、密钥状态、配额和有效期。
- 首次排查时暂时关闭密钥 IP 限制。
- 使用
/v1/models测试密钥认证。 - 从模型广场重新复制模型 ID。
- 检查 Base URL 是否缺少或重复
/v1。 - 确认程序需要 Chat Completions、Responses、Messages 还是 Gemini 原生接口。
- 降低并发，等待一段时间后重试。
错误码对照表
| 错误或现象 | 常见原因 | 解决方法 |
|---|---|---|
API_KEY_REQUIRED | 没有发送密钥 | 使用 Authorization: Bearer YOUR_API_KEY |
INVALID_API_KEY | 密钥错误、不完整或已删除 | 重新复制，检查前后空格 |
API_KEY_DISABLED | 密钥已禁用 | 启用密钥或创建新密钥 |
API_KEY_EXPIRED | 密钥已过期 | 修改有效期或新建密钥 |
API_KEY_QUOTA_EXHAUSTED | 密钥自身配额耗尽 | 提高配额或使用新密钥 |
INSUFFICIENT_BALANCE | 账户余额不足 | 使用兑换码充值 |
ACCESS_DENIED | IP 白名单或黑名单限制 | 检查公网出口 IP 和密钥规则 |
USER_INACTIVE | 账户状态异常 | 联系管理员核对账户状态 |
SUBSCRIPTION_NOT_FOUND | 分组要求订阅 | 更换分组或联系管理员 |
USAGE_LIMIT_EXCEEDED | 达到周期用量上限 | 等待重置或联系管理员 |
API_KEY_AUTH_OVERLOADED | 认证服务暂时繁忙 | 稍后重试并降低并发 |
api_key_in_query_deprecated | Key 放在 URL 参数中 | 改用认证请求头 |
| 401 | 密钥缺失、错误、禁用或过期 | 先测试 /v1/models |
| 402 | 余额或密钥配额不足 | 同时检查余额和密钥配额 |
| 403 | IP 或账户访问限制 | 检查 IP 规则和账户状态 |
| 404 | 路径错误或接口不受支持 | 检查 /v1/v1 和接口类型 |
| 429 | 请求过快或上游限流 | 降低并发，逐渐增加重试间隔 |
| 5xx/无可用渠道 | 上游线路暂时不可用 | 稍后重试或更换模型、分组 |
为什么模型列表正常但生成失败
/v1/models 成功只代表认证和模型列表接口可访问。生成仍可能因以下原因失败：
- 模型不属于当前密钥分组；
- 客户端调用了错误的接口类型；
- 当前线路临时不可用；
- 输入过长或参数不受模型支持；
- 达到并发、速率或用量限制。
为什么流式输出会中断
- 网络代理会缓存或中断 SSE 长连接；
- 客户端超时时间过短；
- 上下文太长，首个 Token 等待时间过久；
- 上游连接临时中断。
可先关闭流式输出测试，再增加超时时间、缩短输入并更换网络。
如何反馈问题
加入 QQ 群 775461964，一次性提供：
- 问题发生时间，精确到分钟；
- 软件名称、版本和操作系统；
- Base URL、模型 ID 和密钥分组；
- HTTP 状态码及完整错误文本；
- 是否使用代理、是否流式；
- 密钥只显示前 3 位和后 4 位，例如
sk-...abcd。
请删除完整 Key、兑换码、密码、验证码、Cookie 和对话隐私后再发送日志。