错误码参考

HTTP 状态码

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

错误响应格式

所有错误响应遵循以下格式：

{
  "error": {
    "message": "错误描述",
    "type": "error_type"
  }
}

任务查询响应中的 error 还包含 code：任务失败时用于说明失败类别；仍在处理时也可能返回 code=task_delayed、type=task_status 的延期提示。任务是否结束只按 status 判断，不能因为 error 非空或 progress=100 就停止查询。以下是失败信息的格式：

{
  "error": {
    "code": "specific_error_code",
    "message": "错误描述",
    "type": "task_error"
  }
}

错误类型

错误类型	对应状态码	描述
`invalid_request_error`	400, 422	请求格式错误或参数校验失败
`authentication_error`	401	API Key 无效、过期或缺失
`insufficient_quota`	402	账户余额不足
`not_found`	404	请求的资源不存在
`rate_limit_error`	429	请求频率超限
`server_error`	500	服务器内部错误
`service_unavailable_error`	422	模型暂时不可用（无可用渠道）

提交阶段错误码

提交任务时，如果参数校验通过但渠道匹配失败，会返回 422 状态码，error.code 字段包含以下错误码：

错误码	描述	建议操作
`unsupported_advanced_options`	请求中的高级参数当前无可用渠道支持	参考响应中的 `unsupported_advanced_options` 字段（每项含参数名与默认值），移除这些参数后重试
`param_constraints_unsatisfiable`	参数值超出当前可用渠道支持的范围	检查参数值是否在文档标注的可选值范围内
`no_compatible_channel`	该模型暂时无可用渠道	稍后重试
`invalid_file_type`	媒体文件的实际内容与期望类型不符	检查文件是否损坏或扩展名与内容不一致

文件类型不匹配（invalid_file_type）

提交任务时，系统会对请求中的媒体文件 URL（image_url、audio_url、video_url 等）进行内容检测。如果文件的实际格式与字段期望的类型不一致（例如 audio_url 指向的文件实际是压缩包），会返回 422 状态码和 invalid_file_type 错误码。响应中包含以下额外字段，便于前端定位问题：

字段	描述
`field`	触发校验失败的参数名（如 `audio_url`）
`detected_type`	检测到的实际 MIME 类型（如 `application/x-tar`）
`expected_type`	期望的媒体类别（`image` / `audio` / `video`）

示例响应：

{
  "error": {
    "message": "The file '002543212992.mp3' is detected as tar 归档文件 (application/x-tar), not a valid audio file. Please verify the file content matches the expected format.",
    "type": "invalid_request_error",
    "code": "invalid_file_type",
    "field": "audio_url",
    "detected_type": "application/x-tar",
    "expected_type": "audio"
  }
}

文件类型检测基于文件头的 magic bytes，不依赖文件扩展名或 HTTP Content-Type header。如果文件本身格式正确但无法识别（如不常见的编码格式），系统会静默放行，不会阻断请求。

高级参数暂不支持（unsupported_advanced_options）

部分参数为高级参数，不是所有渠道都支持。当请求中包含的高级参数在当前模型的所有可用渠道上都不被支持时，会返回 422 状态码和 unsupported_advanced_options 错误码。响应中包含以下结构化字段，便于程序解析：

字段	描述
`model`	触发该错误的模型 ID
`unsupported_advanced_options`	不支持的高级参数列表，每一项包含 `param`（参数名）和 `default_value`（该参数在请求 Schema 中的默认值，移除参数后系统按此值处理）

示例响应：

{
  "error": {
    "message": "The advanced options [enhance_prompt, seed] are not supported by any available channel for model 'veo-3.1'. Remove the unsupported options to proceed.",
    "type": "invalid_request_error",
    "code": "unsupported_advanced_options",
    "model": "veo-3.1",
    "unsupported_advanced_options": [
      {"param": "enhance_prompt", "default_value": false},
      {"param": "seed", "default_value": null}
    ]
  }
}

高级参数在各模型的 API 文档中以 x-advanced 标记。移除不支持的高级参数不影响核心功能，生成结果仍然正常。
default_value 来自请求 Schema 的字段默认值（null 表示该参数本就可选、不传时系统不会附加任何值）。

任务相关错误码

查询任务返回 HTTP 200 只表示查询成功，不表示任务已完成。适用的异步任务处理超过 30 分钟时可能返回以下状态提示：

状态提示码	任务状态与类型	建议操作
`task_delayed`	`status=processing`、`error.type=task_status`	继续查询；按 `message` 了解本任务的实际处理期限。已超过期限但尚未结束时，仍需等待系统处理，不能据此认定已退款。

当 status=failed 时，error.type=task_error，错误码表示安全处理后的失败类别。Gateway 视频、图片、音频和文档任务确认预扣额度已退回时，会在 error.message 追加说明，不改变原有公共 code、type。没有预扣额度的任务无需退款；usage.credits_reserved 退款后仍可为正数，不能据此判断未退款。成功任务始终返回 error=null。具体响应示例见任务查询。失败任务的错误码参考：

错误码	描述	建议操作
`content_policy_violation`	输入内容违反内容策略	修改提示词后重试
`timeout`	任务处理超时	稍后重试；持续失败时联系管理员
`model_unavailable`	当前模型暂不可用	稍后重试；持续失败时联系管理员
`service_unavailable`	服务暂不可用	稍后重试；持续失败时联系管理员

速率限制

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

最佳实践

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

图像系列

视频系列

音频系列

语言系列

文档处理

任务管理

文件管理

HTTP 状态码

错误响应格式

错误类型

提交阶段错误码

文件类型不匹配（invalid_file_type）

高级参数暂不支持（unsupported_advanced_options）

任务相关错误码

速率限制

最佳实践

​HTTP 状态码

​错误响应格式

​错误类型

​提交阶段错误码

​文件类型不匹配（invalid_file_type）

​高级参数暂不支持（unsupported_advanced_options）

​任务相关错误码

​速率限制

​最佳实践

HTTP 状态码

错误响应格式

错误类型

提交阶段错误码

文件类型不匹配（invalid_file_type）

高级参数暂不支持（unsupported_advanced_options）

任务相关错误码

速率限制

最佳实践