故障排查

401 Invalid API key

检查：

• Key 是否复制完整。
• 请求头是否为 Authorization: Bearer YOUR_KEY。
• Key 是否被删除或停用。
• 用户账号是否停用。

403 Access denied

检查：

• Key 是否设置了 IP 白名单。
• 用户余额是否大于 0。
• 订阅是否有效。
• 分组是否启用。

429 限额

检查：

• Key 总额度。
• Key 的 5 小时、1 天、7 天窗口。
• 分组日、周、月额度。
• 用户余额或订阅窗口。
• 上游账号是否限流。

502 Bad Gateway

用户侧可以先重试。管理员应检查：

• request id 对应日志。
• 账号池是否有可用账号。
• 失败账号是否集中在同一网络出口。
• 上游是否返回连接重置、超时、权限错误或额度错误。
• 是否需要临时禁用异常账号或更换出口。

流式请求中断

可能原因：

• 客户端网络断开。
• 上游流式连接断开。
• 代理或反向代理超时。
• 请求输出时间过长。

建议：

• 客户端使用有限重试。
• Nginx 或反代关闭响应缓冲。
• 调整读写超时。
• 降低单次请求上下文长度。

Gemini SDK 报 API key 错误

确认使用 x-goog-api-key 请求头，且 Key 绑定的分组支持 Gemini 或 Mixed 的 gemini_v1beta 入口。