错误

API 使用标准 HTTP 状态码：2xx 表示成功，4xx 表示请求需要修改，5xx 表示我们的服务或上游服务发生故障。所有错误响应采用相同的 JSON 结构，因此可以集中处理。

错误格式#

{
  "error": {
    "code": "invalid_request",
    "message": "\"resolution\" must be one of: 480p, 720p",
    "param": "resolution"
  }
}

• code — 稳定且机器可读的错误代码。请根据此字段编写分支逻辑，不要依赖错误消息。
• message — 适合记录日志的易读说明，措辞可能会调整。
• param — 仅当特定请求字段导致错误时才会返回。

错误代码#

生成任务中的错误#

HTTP 错误表示请求本身被拒绝，不会扣款。已接受后失败的生成与此不同：API 调用仍然成功（即使任务立即失败，POST /run 仍会返回 202），而生成任务的 status 会变为 failed，并包含 error 对象。冻结金额会自动退还。同一对象也会出现在 GET /generations、Webhook 负载和 MCP 工具结果中。

{
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "message": "ByteDance's safety review for Seedance 2.0 Fast rejected this request (the prompt or an input file).",
    "reason": "content_blocked",
    "hint": "Describe the character's look instead of naming a copyrighted character or real person, keep it non-explicit, or try another model.",
    "retryable": false,
    "refunded": true,
    "detail": "你的请求未通过内容安全检查。请调整提示词后重试。"
  }
}

code 是通用错误类别（自产品上线以来记录的四种值）。reason 会准确说明失败原因，请根据此字段编写分支逻辑并向用户展示 message 和 hint。retryable 会说明使用相同请求重试是否可能成功；param 会在可判断时指出需要修改的字段；detail 会保留模型服务提供商的原始措辞。

由请求本身导致的失败（content_blocked、invalid_input 中不被接受的文件、input_unreachable）不会改用其他服务提供商重试，因为仍会以相同方式被拒绝。遇到服务中断和上游错误时，系统会先在所有符合条件的路由中重试，价格保持不变。参见 失败与退款。

当服务商表示无法下载你的某个输入文件时，我们通常会尝试自行下载。如果下载成功，任务会使用我们托管的副本重试——价格不变，你无需进行任何操作；生成记录仍会显示你提交的 URL，副本会按其 保留期限 与生成记录一同删除。因此，input_unreachable 通常表示文件根本无法下载：需要登录、签名链接已过期、链接没有直接指向文件，或文件托管方拒绝了请求。我们可复制最大 30 MB 的图像、200 MB 的视频和 50 MB 的音频；更大的文件或无法读取的文件会以 invalid_input 失败。

安全地重试#

对 429、500、502 和 503 采用指数退避并加入随机抖动后重试。其他 4xx 错误请勿原样重试，否则会以相同方式失败。

const RETRYABLE = new Set([429, 500, 502, 503]);

export async function postWithRetry(url, headers, body, attempts = 5) {
  let resp;
  for (let attempt = 0; attempt < attempts; attempt++) {
    resp = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
    if (!RETRYABLE.has(resp.status)) break;
    // exponential backoff with jitter: ~1s, 2s, 4s, 8s…
    await new Promise((r) => setTimeout(r, Math.min(2 ** attempt, 30) * 1000 + Math.random() * 1000));
  }
  const data = await resp.json();
  if (!resp.ok) throw new Error(`${resp.status} ${data.error.code}: ${data.error.message}`);
  return data;
}

import random, time, requests

RETRYABLE = {429, 500, 502, 503}

def post_with_retry(url, headers, json, attempts=5):
    for attempt in range(attempts):
        resp = requests.post(url, headers=headers, json=json, timeout=30)
        if resp.status_code not in RETRYABLE:
            break
        # exponential backoff with jitter: ~1s, 2s, 4s, 8s…
        time.sleep(min(2 ** attempt, 30) + random.random())
    if not resp.ok:
        err = resp.json()["error"]
        raise RuntimeError(f"{resp.status_code} {err['code']}: {err['message']}")
    return resp.json()

验证示例#

验证错误会指出字段及其允许值，可直接展示给开发者：

[
  {
    "error": {
      "code": "invalid_request",
      "message": "\"prompt\" is required",
      "param": "prompt"
    }
  },
  {
    "error": {
      "code": "invalid_request",
      "message": "Unknown parameter \"resoluton\"",
      "param": "resoluton"
    }
  },
  {
    "error": {
      "code": "not_found",
      "message": "Unknown endpoint \"bytedance/seedance-2.0-fast/text-to-gif\". See GET /api/v1/models."
    }
  }
]

你也可以在不运行任务的情况下查询价格：POST /api/v1/quote/{endpoint} 会验证与价格相关的字段并返回费用。参见 API 参考文档。