はじめに
エラー
HTTP ステータスコード、エラーレスポンスの形式、タスク失敗時の状態について説明します。
エラーレスポンスの形式
失敗したリクエストはすべて、2xx 以外のステータスと同一形式の JSON ボディを返します。
{
"ok": false,
"error": "NOT_ENOUGH_CREDITS",
"message": "Not enough credits: this generation costs 12."
}error は機械可読な固定コードです。message は人間向けの文言で、変更される場合があります。分岐は文言ではなく error で行ってください。
ステータスコード
| ステータス | コード | 意味 |
|---|---|---|
| 400 | INVALID_REQUEST | JSON ボディが不正、またはフィールドが不足しています。 |
| 400 | INVALID_IMAGE_REQUEST | 画像パラメータが不正です。未知のモデル、不正な比率、サイズ超過の参照画像、参照画像の数の超過などが該当します。 |
| 400 | INVALID_VIDEO_REQUEST | 動画パラメータが不正です。未知のモデルやバリアント、未対応の長さ・サイズ・比率などが該当します。 |
| 401 | UNAUTHORIZED | API キーが欠落しているか、無効・失効・期限切れです。 |
| 402 | NOT_ENOUGH_CREDITS | アカウントのクレジットが生成コストに足りません。 |
| 403 | UNAUTHORIZED | アカウントが無効化されています。 |
| 404 | GENERATION_NOT_FOUND | 該当するタスクが存在しないか、別のアカウントのタスクです。 |
| 429 | CONCURRENCY_LIMIT | アカウントのプランで同時に実行できるタスク数の上限を超えています。 |
| 500 | INTERNAL_ERROR | サーバーで予期しないエラーが発生しました。 |
| 503 | SERVICE_CONFIGURATION | 要求された機能がサーバー側で設定されていません。 |
| 503 | MODEL_UNAVAILABLE | 要求された動画モデルが一時的に利用できません。 |
タスクの失敗は HTTP エラーではありません
受け付けられた後に失敗したタスクでも、ポーリング用エンドポイントは 200 を返します。タスクのフィールドを確認してください。
{
"ok": true,
"generation": {
"id": "gen_2f1c9a...",
"status": "failed",
"error": "The model rejected this prompt (content policy).",
"durationMs": 3200,
"imageUrls": []
}
}status | 意味 |
|---|---|
generating | 実行中です。ポーリングを続けてください。 |
success | 完了しました。imageUrls または videoUrls を読み取ってください。 |
failed | エラーで終了しました。error を読み取ってください。 |
失敗したタスクのクレジットは自動的に返還されます。失敗したタスクが再試行されることはありません。もう一度試す場合は新しいリクエストを送信してください。
安全にリトライする
429と5xxのレスポンスは、指数バックオフを伴ってリトライしてください。400、401/403、402、404はリクエストを変更せずにリトライしないでください。同じ理由で再び失敗します。- 受け付けられた
POSTはすべて新しいタスクを作成してクレジットを消費するため、タイムアウト後に無条件でリトライすると二重に課金される可能性があります。まずエラーを確認してください。受け付けられる前にリクエストが拒否されていれば、リトライは安全です。