エラー

Video API endpoints からのすべてのエラーは、同じ JSON shape を使用します：


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

HTTP status は問題の種類を示します。error.code はコード上で分岐に使える安定した文字列です。error.message を parse するのではなく、常に error.code で判定してください。

エラーコード

HTTP	Code	意味
400	`invalid_request`	必須パラメータが欠落している、または値が無効です
400	`invalid_callback_url`	`callback_url` が HTTPS ではない、または private network を指しています（SSRF checks によりブロック）
400	`references_conflict`	`frame_images` と `input_references` が同じリクエストで送信されました（同時使用不可）
400	`too_many_references`	`input_references` が上限を超えています（画像 > 9 / 音声 > 3 / 動画 > 1）
400	`cancel_not_supported`	アップストリームプロバイダーがこの job を中断できません
400	`cancel_failed`	job はすでに終端状態で、キャンセルできません
401	`unauthorized` / `invalid_api_key`	認証に失敗しました
401	`upstream_auth_failed`	アップストリームプロバイダーの認証に失敗しました
402	`insufficient_credits`	job を受理するための残高が不足しています
404	`not_found`	job が存在しない、またはアクセス権がありません
404	`model_not_found`	リクエストされた model が存在しません
429	`rate_limited`	リクエストが多すぎます（ポーリングレート制限またはアップストリームレート制限）
502	`upstream_error` / `route_error`	アップストリームプロバイダーのエラー / ルーティング失敗
500	`internal_error`	予期しない内部エラー

references_conflict と too_many_references は request-body validation errors です。正確な上限は動画を作成をご覧ください。cancel_not_supported と cancel_failed は動画をキャンセルで説明しています。not_found は、未知の job と、別の API key が所有する job の両方で返されます。この2つは意図的に区別できません。

402 残高不足

insufficient_credits は job 作成時（POST /v1/videos）にのみ返されます。事前承認が有効な場合、ofox は job を受理する前に、リクエストされた resolution と duration からコストを見積もります。その見積もりが残高を超える場合、リクエストは即座に拒否されます。job record は作成されず、課金も発生しません。


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

insufficient_credits は Video API が返す唯一の 402 code です。この1つの code を処理し、残高を追加してから再試行してください。

429 レート制限

rate_limited は、GET /v1/videos/{id} の key ごとのポーリング制限と、アップストリームのレート制限の両方を表します。ポーリング制限に達した場合、レスポンスには Retry-After header が含まれます：


HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json
 
{ "error": { "code": "rate_limited", "message": "..." } }

Retry-After header に従い、再試行前にバックオフしてください。頻繁にポーリングしている場合は、webhook 通知に切り替えると、ofox が終端状態を push するため、ポーリング制限を完全に回避できます。Job 作成（POST）とキャンセル（DELETE）はポーリング制限の影響を受けません。