报错和排查
常见报错怎么处理
先按错误码和 request_id 定位问题，再决定是改配置、换模型、充值还是联系支持。
先保存 request_id
报错时不要只截图最后一行。请同时保存错误码、HTTP 状态、request_id、模型名和调用时间，排查会快很多。
常见错误码
常见错误码包括 api_key_missing、api_key_invalid、api_key_query_unsupported、insufficient_balance、model_not_available 和 upstream_quota_exceeded。其中 api_key_query_unsupported 通常表示 Gemini 请求把 Key 放进了 URL 的 ?key=。
Prop
Type
5 步排查法
- 看错误码是不是认证类。如果是，先检查 API Key 和认证字段。
- 看是不是余额不足。如果是，先处理充值或余额。
- 看模型名是不是从顶级AI模型目录复制的。
- 确认工具使用的协议是否正确，比如 Gemini native 不要套 OpenAI-compatible 配置。
- 仍然失败时，把
request_id发给支持人员。
错误响应长什么样
顶级AI 的错误响应通常包含 error.code、error.message 和 request_id。部分网关错误会把 request_id 放在 error.request_id 里，客户端排查时两种位置都要兼容。
upstream_message 只是安全摘要，不会承诺原样展示上游返回的全部错误正文。