跳转到主要内容

​
HTTP 状态码

状态码描述常见原因
200成功请求处理成功
400请求格式错误JSON 格式错误、Content-Type 不正确
401未授权API Key 无效、过期或缺失
402余额不足账户余额不足，请充值后重试
404未找到任务 ID 不存在
422参数校验失败缺少必填字段、参数值不合法、模型不存在
429请求频率超限超出速率限制，请稍后重试
500服务器内部错误服务端未知错误，请稍后重试
503服务暂不可用当前模型无可用渠道或上游服务异常，请稍后重试

​
错误响应格式

所有错误响应遵循以下格式： 
{
  "error": {
    "message": "错误描述",
    "type": "error_type"
  }
}
任务失败时，任务查询响应中的 error 字段包含额外的 code 字段： 
{
  "error": {
    "code": "specific_error_code",
    "message": "错误描述",
    "type": "task_error"
  }
}

​
错误类型

错误类型对应状态码描述
invalid_request_error400, 422请求格式错误或参数校验失败
authentication_error401API Key 无效、过期或缺失
insufficient_quota402账户余额不足
not_found404请求的资源不存在
rate_limit_error429请求频率超限
server_error500服务器内部错误
service_unavailable_error422模型暂时不可用（无可用渠道）

​
提交阶段错误码

提交任务时，如果参数校验通过但渠道匹配失败，会返回 422 状态码，error.code 字段包含以下错误码：
错误码描述建议操作
unsupported_advanced_options请求中的高级参数（advanced）当前无可用渠道支持响应中的 unsupported_options 列出了不支持的参数名，移除后重试
param_constraints_unsatisfiable参数值超出当前可用渠道支持的范围检查参数值是否在文档标注的可选值范围内
no_compatible_channel该模型暂时无可用渠道稍后重试
示例响应： 
{
  "error": {
    "message": "The following advanced options are not currently supported for model 'veo-3.1': enhance_prompt. Remove these options to proceed, or try again later.",
    "type": "invalid_request_error",
    "code": "unsupported_advanced_options",
    "unsupported_options": ["enhance_prompt"]
  }
}

​
任务相关错误码

查询任务状态时，状态为 failed 的任务会在 error.code 字段中包含以下错误码：
错误码描述建议操作
task_failed任务执行失败（通用）重新发起请求
content_policy_violation输入内容违反内容策略修改提示词后重试
invalid_image_url提供的图像/视频 URL 无法访问检查 URL 是否公开可访问
file_too_large上传的文件超出大小限制减小文件大小
unsupported_format不支持的文件格式使用支持的格式

​
速率限制

  • 速率限制按 API Key 应用
  • 被限速时返回 429 状态码，请等待后重试
  • 如需更高速率限制，请联系客服

​
最佳实践

  1. 始终检查 HTTP 状态码 再解析响应体
  2. 实现指数退避 对 429 和 5xx 错误进行重试
  3. 记录错误响应 用于调试和排查
  4. 合理轮询任务状态 建议间隔 3-5 秒，避免过于频繁
  5. 优雅处理异步任务 生成任务耗时因模型而异，请参考各模型文档中的预计时间