エラー

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は大分類です（提供開始時から変わらない4つの値）。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リファレンスをご覧ください。