排错与帮助
错误码
按 HTTP 状态码定位原因，附自查清单。
先看 HTTP 状态码，再看响应体里的错误信息。多数工具会把两者一起打印出来。
401密钥无效
- 现象
- 401 Unauthorized；工具提示 API Key 无效或认证失败。
- 常见原因
- 密钥复制不完整；密钥已被删除；OpenAI 协议下请求头缺少 Bearer 前缀；密钥填到了别的协议的字段里。
- 处理
- 重新从控制台复制密钥；确认请求头格式正确；仍不行就新建一把密钥。
- 是否计费
- 不计费。
403余额或配额不足 / 无权访问
- 现象
- 403，或提示余额、配额、订阅不足；也可能是该分组不允许访问此模型。
- 常见原因
- 余额用完；套餐配额尚未重置；Key 绑定的分组不包含该模型或该协议。
- 处理
- 到控制台查看余额与用量；充值或等待配额重置；换一把绑定了合适分组的密钥。
- 是否计费
- 请求未执行，不计费。
404地址或模型不存在
- 现象
- 404 Not Found；或提示 model not found。
- 常见原因
- Base URL 多了或少了 /v1；Gemini 协议误用了 /v1；模型名拼写错误或不在模型广场列表中。
- 处理
- 对照「Base URL」一页检查地址；到模型广场复制准确的模型名。
- 是否计费
- 不计费。
413请求体过大
- 现象
- 413 Payload Too Large.
- 常见原因
- 上下文、附件或对话历史超出限制。
- 处理
- 精简上下文，去掉无关文件，或开新会话。
- 是否计费
- 不计费。
429请求过于频繁
- 现象
- 429 Too Many Requests；工具突然连不上或反复失败。
- 常见原因
- 并发过高；多个工具或会话同时在跑；客户端重试间隔太短。
- 处理
- 降低并发，关闭多余的客户端，稍等片刻再试。
- 是否计费
- 未完成的请求不计费。
5xx上游或网关异常
- 现象
- 500 / 502 / 503 / 504.
- 常见原因
- 上游模型服务波动；网络抖动；临时维护。
- 处理
- 稍后重试，或先换一个模型。持续出现请提交工单。
- 是否计费
- 按实际产生的用量计费，以控制台用量记录为准。
快速自查清单
以上都确认过仍失败，到控制台 工单 反馈，附上时间、模型名、状态码与响应体。