08 错误码与边界

全部 HTTP 状态码 + 错误码 + 限制 + 内容审核行为。

错误响应格式

所有错误都返回 OpenAI 风格的 error 对象:

json

{
  "error": {
    "code": "...",
    "message": "...",
    "type": "..."        // 有时存在
  }
}

HTTP 状态码总表

状态码	类型	何时出现
200	成功	任务创建成功 / 查询成功
400	客户端错误	参数错误(模型名, 内容缺失, 分辨率不支持等)
401	未认证	没传 Bearer token 或 token 格式错
402	余额不足	预扣额度超过当前余额
403	禁止	引用了不属于你的素材 / group
404	不存在	task_id / asset_id / group_id 不存在或不属于你
410	资源失效	视频 URL 已过期(24h)
425	还没准备好	用 `/content` 接口时任务还在跑
429	限流	API 调用频率超限
500	服务器错误	平台内部错误, 请重试 / 联系运营
502	上游错误	上游官方不可用
503	服务不可用	平台维护 / callback secret 未配

错误码详解

400 Bad Request

`invalid_request_error` — 通用参数错误

json

{
  "error": {
    "type": "invalid_request_error",
    "message": "model is required"
  }
}

常见原因:

model 字段缺失
model 不在支持列表
content 数组为空
字段类型错(比如 duration 传成字符串)

`unsupported_resolution` — 分辨率不支持

json

{
  "error": {
    "code": "unsupported_resolution",
    "message": "seedance-2.0-fast does not support 1080p resolution"
  }
}

修复: Fast 模型最高 720p, 想要 1080p 用 Pro 模型。

`v2v_requires_video_url` — v2v 模型缺 video_url

json

{
  "error": {
    "code": "v2v_requires_video_url",
    "message": "v2v models require at least one video_url content item"
  }
}

修复: 用 v2v 模型时必须在 content 里放 video_url 项。

`text_required` — text 项缺失

json

{
  "error": {
    "code": "text_required",
    "message": "content must include at least one text item"
  }
}

修复: content 数组里至少要有一个 {"type": "text", "text": "..."}。

`duration_out_of_range` — 时长越界

json

{
  "error": {
    "code": "duration_out_of_range",
    "message": "duration must be between 4 and 15 seconds (or -1 for auto)"
  }
}

修复: duration 改成 4-15 整数, 或 -1。

`upstream_rejected` — 上游(内容审核)拒绝

json

{
  "error": {
    "code": "upstream_rejected",
    "message": "prompt contains restricted content: violence"
  }
}

修复: 修改 prompt, 避免敏感内容(暴力 / 色情 / 政治 / 真人未授权肖像等)。预扣会全额退还。

401 Unauthorized

json

{
  "error": {
    "message": "Bearer token required"
  }
}

修复: 检查 Authorization: Bearer sk-xxx 头部, key 是否正确。

402 Payment Required

json

{
  "error": {
    "code": "insufficient_quota",
    "message": "Pre-consume quota exceeds available balance. Required: 4500000, Available: 1234"
  }
}

修复: 充值, 或减少 duration / 分辨率。Required 和 Available 单位是 quota(÷ 500000 ÷ USDExchangeRate ≈ CNY)。

403 Forbidden

json

{
  "error": {
    "code": "asset_ownership_violation",
    "message": "asset asset-xxx does not belong to current user"
  }
}

修复: 你引用了别人的素材, 或素材 ID 拼错。检查 asset:// URI。

404 Not Found

json

{
  "error": {
    "code": "not_found",
    "message": "task cgt-xxx not found"
  }
}

可能原因:

task_id 拼错
任务属于其他用户(出于安全, 我们返回 404 不返回 403)
任务已被删除

410 Gone — 视频 URL 过期

json

{
  "error": {
    "code": "video_url_expired",
    "message": "video URL has expired (URLs valid for 24h)"
  }
}

修复: 重新生成视频。预防方法: 任务完成后立即下载或转存。

425 Too Early

json

{
  "error": {
    "code": "task_not_completed",
    "message": "task is still in_progress"
  }
}

修复: 先用 GET /v1/videos/:task_id 查 status, 看到 completed (Volcengine 路由是 succeeded) 再去拿视频。视频 URL 在响应的 metadata.url 字段。

429 Too Many Requests

json

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests"
  }
}

修复: 降低调用频率。常见 rate limit:

全局 API: 180 次 / 180 秒(每 IP)
单 token: 看 token 设置

轮询任务时: 间隔 ≥ 5 秒, 推荐 10 秒。

500 / 502 / 503 — 服务器错误

json

{
  "error": {
    "code": "internal_error",
    "message": "..."
  }
}

策略:

500: 平台内部错误, 退避重试(1s, 2s, 4s)
502: 上游官方不可用, 退避重试(5s, 10s, 20s)
503: 平台维护 / 配置缺失, 等待 + 联系运营

内容审核

谁审核?

完全由上游官方审核, 平台不做本地审核。

触发情况

暴力 / 血腥 / 武器 / 战争
色情 / 裸体 / 性暗示
政治敏感 / 历史敏感人物
真人未授权肖像(明星 / 公众人物等)
仇恨言论
违法犯罪

行为

如果触发审核, 任务进入 failed 状态(两种路由风格都是 failed), 返回:

json

{
  "id": "cgt-xxx",
  "status": "failed",
  "progress": 100,
  "error": {
    "code": "1",
    "message": "upstream task failed: content moderation rejected prompt"
  },
  "metadata": {"url": ""}
}

预扣费会全额退还。

建议

测试时用清晰、中性、描述性的 prompt
避免引用真实姓名(用"一个年轻人"代替"张三")
不确定时, 先用小成本(fast + 480p + 4s)试

限制汇总

限制	数值	备注
视频时长	4-15 秒	-1 表示自动
分辨率	480p / 720p / 1080p	Fast 不支持 1080p
单任务最大 prompt	推荐 < 500 字	上游硬限制约 1500 字
视频 URL 有效期	24 小时	必须及时下载或转存
全局 API 限流	180 次 / 180 秒 / IP	真实客户 IP 维度
同时进行的任务数	无显式限制	受余额制约
任务最长执行时间	通常 < 10 分钟	上游 24h 后强制 expire
Callback URL 要求	公网可达, 响应 < 1s + 返回 2xx	不强制 HTTPS 但强烈推荐;详见 04 回调

调试技巧

1. 看 request_id 定位问题

每个响应里都有 request_id(在 header 或 body 里):

http

X-Oneapi-Request-Id: 202605271234567...

报问题给运营时带上 request_id, 我们能立即定位日志。

2. 先小成本试错

bash

# 用最便宜的组合调试 prompt
curl ... -d '{
  "model": "seedance-2.0-fast",
  "content": [{"type":"text","text":"YOUR PROMPT"}],
  "resolution": "480p",
  "duration": 4
}'

成功 + 想要的画面 → 升级到 pro / 1080p / 10s 生成商用版本。

3. 用 dry-run(平台暂未支持)

如果想"只算钱不真生成"的 dry-run, 平台暂不支持。建议办法: 提交真实任务 + 立即 cancel(目前没 cancel API, 等任务自然 expired 全额退款)。

联系支持

报告问题时, 提供:

request_id(关键)
出错的 endpoint + body
完整错误响应
期望的行为

联系方式: 看代理商配置的"联系邮箱"。

回到文档目录

08 错误码与边界 ​

错误响应格式 ​

HTTP 状态码总表 ​

错误码详解 ​

400 Bad Request ​

invalid_request_error — 通用参数错误 ​

unsupported_resolution — 分辨率不支持 ​

v2v_requires_video_url — v2v 模型缺 video_url ​

text_required — text 项缺失 ​

duration_out_of_range — 时长越界 ​

upstream_rejected — 上游(内容审核)拒绝 ​

401 Unauthorized ​

402 Payment Required ​

403 Forbidden ​

404 Not Found ​

410 Gone — 视频 URL 过期 ​

425 Too Early ​

429 Too Many Requests ​

500 / 502 / 503 — 服务器错误 ​

内容审核 ​

谁审核? ​

触发情况 ​

行为 ​

建议 ​

限制汇总 ​

调试技巧 ​

1. 看 request_id 定位问题 ​

2. 先小成本试错 ​

3. 用 dry-run(平台暂未支持) ​

联系支持 ​

08 错误码与边界

错误响应格式

HTTP 状态码总表

错误码详解

400 Bad Request

`invalid_request_error` — 通用参数错误

`unsupported_resolution` — 分辨率不支持

`v2v_requires_video_url` — v2v 模型缺 video_url

`text_required` — text 项缺失

`duration_out_of_range` — 时长越界

`upstream_rejected` — 上游(内容审核)拒绝

401 Unauthorized

402 Payment Required

403 Forbidden

404 Not Found

410 Gone — 视频 URL 过期

425 Too Early

429 Too Many Requests

500 / 502 / 503 — 服务器错误

内容审核

谁审核?

触发情况

行为

建议

限制汇总

调试技巧

1. 看 request_id 定位问题

2. 先小成本试错

3. 用 dry-run(平台暂未支持)

联系支持