> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# エラー早見表

> API リクエストエラーとタスクの失敗理由を確認し, 入力の修正や送信結果の復旧に役立てます

リクエストの失敗と生成タスクの失敗を区別してください. `invalid_request` は画像サイズの制約違反でも返されるため, 画像入力が非対応とは限りません.

## エラーを読む場所

| 場面 | 判定方法 | 確認するフィールド |
| - | - | - |
| OpenAI 形式のリクエストエラー | HTTP エラーまたはエラーオブジェクト | `error.code`, `error.message`, 任意の `error.param`, `error.type` |
| 一部のタスク送信/照会エンドポイントのリクエストエラー | HTTP ステータスと本文の両方を確認 | トップレベルの `code`, `message`, `data` |
| タスク実行の失敗 | 照会は成功してもタスクの `status` が `failed` | `error.code`, 任意の `error.reason`, `error.message` |
| タスク Webhook の失敗イベント | `type` が `generation.failed`, `data.status` が `FAILURE` | `data.error.code`, `data.error.message` |
| 動画リクエストの復旧 | 復旧レコードの `state` を確認 | 任意の `error_code`, `message`, `task_id` |

説明用のリクエストエラー例:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "type": "toapis_error",
    "param": "",
    "message": "Image dimensions or aspect ratio do not meet this model's requirements."
  }
}
```

タスク実行の失敗例:

```json theme={null}
{
  "id": "task_example",
  "object": "generation.task",
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "reason": "image_dimensions_multiple",
    "message": "Image dimensions must be multiples of 16."
  }
}
```

例の倍数は全モデル共通の制限ではありません. HTTP 200 は照会成功を示すだけなのでタスク状態も確認してください. 数字の業務 `code` は HTTP ステータスとは別です. `success: false` の本文も確認してください.

`code` はエラー識別, 任意の `reason` はタスク失敗の分類, `message` は具体的な説明です. `error.type` は必ずしもコードと一致しません. メッセージは言語で変わるため完全一致で処理を分岐しないでください. 認証エラーの `code` が空の場合や, `type` と `message` だけの形式もあります.

## リクエストエラー早見表

公開 API で発生し得る識別子です. すべてのエンドポイントが全項目を返すわけではなく, モデル固有の表記が残る場合もあります. フィールドの位置は上表で確認してください.

| エラー識別子 | 考えられる原因 | 対応 |
| - | - | - |
| `invalid_request`, `invalid_request_error`, `invalid_params`, `InvalidParameter`, `invalid_parameter_error`, `invalid_value` | 型, 画像サイズ, 素材の取得, メッセージ構造, パラメータの組み合わせが無効 | `param` と `message` で対象を特定し, 下の具体例に従って修正してから再送信 |
| `invalid_json`, `invalid_multipart_form`, `read_request_body_failed` | JSON/フォームの解析や本文の読み取りに失敗 | シリアライズ, `Content-Type`, アップロードの完了を確認 |
| `unknown_parameter`, `unsupported_value`, `provider_capability_not_supported`, `not_supported` | モデルがフィールド, 値, ツール, エンドポイントの機能を受け付けない | 対象モデルの仕様を確認し, 非対応の項目を除くか対応モデルを選択 |
| `missing_model`, `model_not_found`, `unsupported_model`, `DeploymentNotFound` | モデル名の欠落, アクセス不可, 非対応のエンドポイント, 一時的な利用不可 | [モデル一覧](https://docs.toapis.com/docs/ja/api-reference/models.md)と API Key の権限を確認. 名前が正しく一時的な障害の場合は待って再試行するかサポートへ連絡 |
| `invalid_private_assets`, `invalid_image`, `invalid_image_file` | 無効な素材参照, デコード不可, 枚数/サイズ超過, URL の取得失敗 | 該当素材と制限を確認し, 再エクスポートまたは再アップロード |
| `access_denied`, または code のない HTTP 401/403 | API Key の無効化, 期限切れ, 停止, IP/モデルの権限制限 | キーと権限を確認. サービス側の認証エラーが利用者自身のキーの不備を意味するとは限らない |
| `insufficient_user_quota`, `quota_not_enough`, `token_quota_not_enough`, `pre_consume_token_quota_failed` | アカウント残高, Token の利用枠, 期間上限の不足, または確認処理の一時的な失敗 | 自分のアカウント/Token と明示された場合だけ入金や上限変更を行う. サービス側の問題は待って再試行するかサポートへ連絡 |
| `rate_limit_exceeded`, `RateLimitReached`, `rate_limit_unavailable` | 頻度制限, モデルサービスの制限, 利用枠の確認不可 | 同時実行数を下げ, `Retry-After` を優先し, ランダムな待機を含むバックオフを使用. [非同期制限](https://docs.toapis.com/docs/ja/api-reference/rate-limits/async-tasks.md)を参照 |
| `get_channel_failed`, `all_channels_circuit_broken`, `provider_unavailable` | 利用可能なモデルサービスがない, または高負荷 | 待って再試行し, 継続する場合はサポートへ連絡. 画像内容の変更は不要 |
| `do_request_failed`, `first_output_timeout`, `up_timeout` | 接続, 最初の出力, 応答読み取りのタイムアウト. 受理済みの可能性あり | タスク ID があれば先に照会. ID のない動画リクエストは下の復旧手順に従う |
| `bad_response_status_code`, `bad_response`, `bad_response_body`, `read_response_body_failed`, `upstream_error`, `unknown_error` | サービスのエラー, 応答の読み取り/解析失敗 | HTTP ステータスと説明を確認し, 既存タスクの有無を調べる. 継続する場合はリクエスト ID を添えて連絡 |
| `convert_request_failed`, `model_price_error`, `pricing_failed`, `pricing_unavailable`, `internal_error` | リクエスト変換, 料金計算, サービス処理の失敗. 入力が原因とは限らない | 明確なフィールド制約があれば修正. それ以外は待って再試行するか連絡 |
| `task_not_found`, `task_not_exist`, `request_not_found` | タスク/復旧レコードがない, 別アカウントの ID, 復旧レコードの期限切れ | ID, アカウント, 照会先を確認. 復旧レコードがないことは未実行の証拠にはならない |
| `invalid_client_request_id`, `request_cache_unavailable`, `submission_unconfirmed` | 復旧 ID が無効, 復旧サービスが利用不可, 送信結果が未確認 | ID 形式を修正するか元のリクエストを照会. 新しい ID で連続送信しない |
| `invalid_callback_url`, `callback_url_origin_mismatch`, `webhook_not_configured`, `webhook_configuration_invalid`, `webhook_configuration_unavailable`, `webhook_configuration_error`, `webhook_api_token_required` | コールバック URL/Token の Webhook 設定が無効, または設定を取得できない | [タスク Webhook](https://docs.toapis.com/docs/ja/api-reference/webhooks/task-webhooks.md)で HTTPS, オリジン, API Token, 設定を確認 |
| `sensitive_words_detected`, `prompt_blocked`, `content_policy_violation`, `content_filter`, `content_filtered` | 入力または生成結果がコンテンツ審査に不合格 | プロンプトとすべての参照素材を確認し, 規定に沿って修正. 同じリクエストを自動再送しない |
| `invalid_encrypted_content` | 会話の出力項目に含まれる暗号化内容を検証/解析できない | クライアントが過去の出力を変更/切り詰めていないか確認し, そのまま保持. 暗号化内容を書き換えず, 継続する場合は連絡 |

## invalid\_request の具体的な原因

実際のリクエストと失敗タスクの診断から整理した例です. 汎用パラメータコード, 詳細な `reason`, モデル固有コードで返る場合があります. 変更前に対象フィールドと説明を確認してください.

| 具体的な状況 | 確認と修正 |
| - | - |
| 出力サイズや比率の書式が違う | `size` に `1:1` などの比率だけを受け付けるモデルも, ピクセルサイズを受け付けるモデルもある. 比率専用のモデルへ `1024x1024` を送ると失敗する. 各モデルの `size`, `resolution`, `aspect_ratio` の定義に従う |
| 幅, 高さ, 総画素数, 寸法の倍数が制約外 | 小さすぎる, 大きすぎる, 横長すぎる, 指定倍数でない場合がある. 参照画像と出力サイズを区別し, 対象モデルの制限に合わせて縮放/切り抜き |
| 参照画像のファイルや枚数が上限超過 | バイト数, 長辺, 総画素数, 枚数は別の制限. 圧縮しても画素数が減るとは限らない. エラーに応じて圧縮, 縮小, 枚数削減 |
| 画像フィールドの型が違う | URL 文字列の配列を要求する API にオブジェクト配列は渡せない. `image_urls` と `image_with_roles` は構造が異なり, Base64 や両方の併用を認めない入口もある |
| URL はあるがファイルを取得できない | 403/404, ログイン必須, URL 期限切れ, タイムアウト, 直リンク制限, HTML 応答が原因になる. 十分な有効期間の公開直接ダウンロード URL か[アップロード API](https://docs.toapis.com/docs/ja/api-reference/uploads/images.md)を使用 |
| 素材の形式や長さが非対応 | 拡張子が正しくてもデコードできるとは限らない. GIF, 動画コーデック, フレームレート, 個別/合計の長さをモデル仕様に合わせて再エクスポート |
| Seedance のタスク種別とパラメータが矛盾 | 編集と判定されると `aspect_ratio=adaptive`, `duration=-1` が必要な場合がある. 延長も `adaptive` を要求する場合がある. `InvalidParameter.TaskTypeConstraint` は別種別と判定された場合にも発生. [Seedance 2.5](https://docs.toapis.com/docs/ja/api-reference/videos/seedance-2-5/generation.md)を参照 |
| テキスト, 会話履歴, ツール呼び出し順序の不備 | プロンプト超過, 非対応の `developer` ロール, `tool_calls` に対応するツール結果の欠落, 思考モードの `reasoning_content` 欠落など. 対象モデルのプロトコルに合わせる |
| フィールド自体はあるが対象モデルでは無効 | `quality`, `reasoning_effort`, `temperature`, `thinking`, `enable_thinking` は共通仕様ではない. `max_tokens` と `max_completion_tokens` は排他的な場合がある. ツール Schema と `response_format` も仕様を確認 |

過去のエラーの数値は全モデル共通ではありません. 画像入力への対応はモデル仕様で判断し, `invalid_request` や `invalid_image` だけで判断しないでください.

## タスクの失敗理由

ID 取得後は照会状態に従います. 通常の生成失敗では `error.code=generation_failed` がよく使われ, 任意の `error.reason` が詳細を示します. 以下は reason 値であり, リクエストの code として必ず返るわけではありません.

`error.input_media_errors` がある場合は各項目の `type`, `index`, `message` を確認します. `type=image`, `index=0` は元のリクエストの最初の画像を示すため, その素材を修正できます. 全モデルや照会形式で提供されるわけではありません.

| error.reason | 考えられる原因と対応 |
| - | - |
| `invalid_input`, `missing_parameter` | 入力が無効または必須項目が不足. 上の具体例と説明を確認して修正 |
| `reference_image_too_large`, `image_dimensions_multiple` | 参照画像のファイルサイズまたは寸法の倍数制約. バイト数とピクセルサイズを別々に確認 |
| `reference_media_unreadable`, `unsupported_media_format` | URL 取得不可, ファイルが無効, 非対応形式. アクセスと実際のメディアを確認 |
| `unsupported_parameter_value`, `parameter_out_of_range`, `parameter_replacement_required` | 許可されない値, 範囲外, フィールドの置き換えが必要. 説明とモデル仕様に従う |
| `video_edit_parameters_required`, `unsupported_request_capability` | 編集パラメータの組み合わせが無効, または機能が非対応. 種別, パラメータ, モデルを調整 |
| `content_policy_rejected` | プロンプト, 参照画像/動画/音声, 生成出力が安全性/著作権審査に不合格. 全入力を確認. 入力が適切でも出力で拒否される場合がある |
| `service_busy`, `request_rate_limited` | 高負荷または頻度制限. 待機して頻度を下げる |
| `generation_timeout` | 生成や処理のタイムアウト. 既存タスクを確認し, 処理中に重複生成しない |
| `generation_unavailable`, `model_unavailable`, `model_region_unavailable` | モデルサービスの一時的な利用不可または対象地域で非対応. モデルと権限を確認し, 継続する場合は連絡 |
| `insufficient_user_balance`, `token_quota_exceeded` | 自分のアカウント残高や API Token の利用枠が不足. 両方と期間上限を確認 |
| `result_storage_failed` | 結果の保存/配信に失敗. 入力非対応とは限らない. タスク ID を添えて連絡 |
| `submission_pending_reconciliation` | 送信や生成結果の確認待ち. 既存 ID を保持し, 重複生成せず照会結果を待つ |
| `refund_pending` | 失敗タスクの返金処理中. 新しい照会の課金情報を確認し, 継続する場合は連絡 |
| `request_cancelled` | リクエスト/タスクがキャンセルされた. 意図した取消か確認してから再送信を判断 |
| `generation_failed`, `service_error` | 詳細な公開理由がない, または内部処理に失敗. タスク/リクエスト ID を保持して連絡 |

一部モデルは `InvalidParameter.TaskTypeConstraint`, `RateLimitReached`, `InputImageSensitiveContentDetected`, `OutputVideoSensitiveContentDetected` などをそのまま返します. 順にタスク制約, 制限, 入力審査, 出力審査に関係する場合があります. 網羅的な一覧ではありません.

Seedance Global の `error.code` と `error.message` は元の JSON 値を保持し, 数字や `null`, 省略もあり得ます. OpenAI 動画形式や Webhook は `reason` を保証しません. 未知のコード, 省略, 型の違いを許容し, 元の数字コードを HTTP ステータスと解釈しないでください.

## 再試行と送信結果の復旧

* パラメータ, 形式, 内容審査: 入力を修正してから再送信します. 変更なしの再試行では通常解決しません.
* 頻度制限や一時的な利用不可: `Retry-After` を優先し, なければジッター付き指数バックオフと回数制限を使います.
* タスク ID がある場合: 同じタスクを照会するか[タスク Webhook](https://docs.toapis.com/docs/ja/api-reference/webhooks/task-webhooks.md)を受信します. `queued` と `in_progress` は失敗ではなく, 重複作成は不要です.
* 動画送信のタイムアウトや `submission_unconfirmed`: 元の送信で `client_request_id` を使用した場合, 同じアカウントで `GET /v1/video/requests/{client_request_id}` を呼びます. `task_id` があれば照会し, `submitting` / `unknown` なら待機します. `state=failed` かつ `error_code=submission_rejected` の場合だけ拒否を確認でき, 案内に従って新規送信できます. この機能は対応する動画入口で当該フィールドを使用した場合に限ります.

失敗と返金完了は別です. [課金情報](https://docs.toapis.com/docs/ja/api-reference/account/pricing.md)の利用可能な `billing` を確認してください. 省略は無料や返金完了を意味しません. Webhook はイベントのスナップショットであり, 後の照会と課金フィールドが異なる場合があります.

## サポートへの連絡

時刻とタイムゾーン, モデル, エンドポイント, HTTP ステータス, リクエスト ID, 利用可能なタスク ID, code/reason, 機密情報を除いた説明を添えてください. 画像は寸法, 形式, ファイルサイズで十分です. API Key, 署名付き URL, プロンプト全文, 非公開素材を送らず, 再現には公開可能な最小例を使ってください.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.