错误码

错误响应格式与常见错误码排查指引

错误响应格式

出错时返回非 2xx 状态码，响应体为 JSON：

{
  "error": {
    "message": "无可用渠道 (distributor) (request id: ...)",
    "type": "focal_api_error",
    "code": "insufficient_quota"
  }
}

排查时请同时记录 HTTP 状态码、error.code 与响应头/响应体中的 request id。

常见错误码

HTTP	code	含义	处理建议
400	`invalid_request_error`	参数缺失/非法（如 `duration` 超限、模型名错误）	对照 API 参考检查参数
401	`invalid_api_key`	密钥缺失、无效或已删除	检查 `Authorization` 头与令牌状态
402	`insufficient_quota`	余额不足（含预扣超限）	充值后重试；检查令牌额度限制
403	`permission_denied`	无该模型/功能权限	确认分组与令牌模型范围
429	`rate_limit_exceeded`	触发限流	降低并发，指数退避重试
500	`internal_error`	服务端错误	带 request id 联系运营方
501	`endpoint_unavailable`	端点未实现/未开放（如 Files、Fine-tunes）	换用已开放端点
502/503	`upstream_error`	上游模型服务异常	稍后重试；持续失败联系运营方

异步任务错误

视频等异步任务创建后失败不算 HTTP 错误——任务状态变为 failed，错误信息在任务的 error 字段，费用自动退回。

排障 checklist

状态码与 error.code 是什么？
同一密钥在控制台 Playground 能否调通？（区分「配置问题」与「代码问题」）
模型名是否与 GET /v1/models 完全一致？
流式请求是否漏处理 SSE 分帧？

Gemini 图片(Nano Banana)

上一页

本页目录

错误响应格式常见错误码异步任务错误排障 checklist