错误
错误响应格式、所有错误码，以及哪些错误可以重试。
错误格式
所有错误响应都是这个结构：
{
"error": {
"code": "insufficient_balance",
"message": "Your available balance is not enough to create this task.",
"param": null,
"details": { "required": "1.50", "available": "0.80" },
"request_id": "rq_01jb..."
}
}| 字段 | 说明 |
|---|---|
code | 机器可读的错误码，程序应以它为准 |
message | 给人看的说明（英文），内容可能调整，不要用于程序判断 |
param | 出错的参数名，没有则为 null |
details | 可选，附加信息 |
request_id | 同响应头 X-Request-Id |
HTTP 状态码与错误码
| 状态码 | code | 说明 | 是否可重试 |
|---|---|---|---|
| 400 | invalid_request | 参数缺失、类型或取值不合法 | 否，修正参数 |
| 400 | invalid_media | 源视频读不了：链接打不开或已过期、不是公网地址、不是视频或格式不支持（支持 mp4、mov、webm、mkv）。details.reason 是具体原因 | 否，换一个视频链接 |
| 400 | video_too_long | 源视频超过 30 秒。details.video_duration 是视频时长（秒） | 否，裁剪后重新创建 |
| 400 | video_too_short | replace_object 的源视频不到 4 秒 | 否 |
| 401 | invalid_api_key | Key 不存在、已删除或已被重置 | 否 |
| 402 | insufficient_balance | 可用余额不足以冻结本次费用；details 中给出所需金额和可用余额 | 充值后可重试 |
| 403 | account_suspended | 账号已被停用 | 否 |
| 404 | not_found | 任务不存在，或不属于当前用户 | 否 |
| 429 | rate_limited | 超过频率限制 | 按 Retry-After 重试 |
| 429 | too_many_inflight_tasks | 进行中的任务已达上限（details.limit） | 等排队中或运行中的任务结束一个后重试 |
| 500 | internal_error | 服务端错误，任务没有创建 | 可以 |
| 503 | service_unavailable | 暂时无法计算价格，任务没有创建 | 可以，按 Retry-After 等待后重试 |
处理建议
- 以
code判断，不要只看状态码或message：两种429的处理方式不同。 402 insufficient_balance：details.required是本次需要的金额，details.available是可用余额。充值后重试，见计费规则。- 只要返回了错误，就没有创建任务，也没有扣费。
任务创建后的失败
上表是请求本身返回的错误。任务创建成功后仍可能失败，例如参考图打不开、素材内容不合规：任务以 status: "failed" 结束，原因在 error 字段（见失败原因），冻结金额全额退回。