GPT Image 2.5 is live — OpenAI's newest image model, targeted edits that leave the rest of the frame alone
すべてのガイド

· reAPI Team

API 500エラー:動画リクエストを再試行するタイミング

API 500エラーに対処し、有料動画ジョブの重複を防ぎます。送信が受理されたか確認し、タスクIDを復元して、再試行を制限しながらワークフローを安全に再開します。

API 500エラー:動画リクエストを再試行するタイミング

一度クリックし、エラーメッセージが表示され、もう一度クリックする。動画アプリでは、画面に失敗と表示されたまま、有料の生成が2件作成されることがあります。

仮のリクエストを考えてみましょう。サーバーは最初の送信を受理してタスクを開始しますが、応答がクライアントに戻る途中で失われます。クライアントはエラーを受け取り、再送信します。エンドポイントが受理した送信ごとに新しいタスクを作成するなら、両方のジョブが続行する可能性があります。2回目のクリックは最初の応答を修復したのではなく、別の動画を要求したのです。

これがAPI 500エラーに伴う実務上の難しさです。AWSの再試行ガイダンスは、応答失敗やタイムアウトだけでは、操作に副作用がなかったとは判断できないと注意しています。[1] 生成を再試行する前に、失敗したリクエストが何をしていたのか、受理されたことを示す証拠が残っているかを確認してください。

失敗したリクエストを特定する

「Request failed with status code 500」のようなメッセージが示すのはHTTPの結果であり、動画の状態ではありません。MDNは500を、リクエストの完了を妨げた予期しないサーバーの状態と定義しています。[2] どのコンポーネントで障害が起きたのか、すべての入力が有効だったのか、待てば直るのかは分かりません。

クライアントログでメソッドとURLを確認してください。生成POSTの失敗と、既存タスクの取得時の失敗では、結果が異なります。前の2つの操作が成功した後に、ファイルのダウンロードだけが失敗することもあります。これら3つをすべて「生成失敗」にまとめるインターフェースでは、復旧に必要な違いが失われます。

UTC時刻、モデル、ステータス、レスポンス本文、利用可能なリクエストIDまたはタスクIDを記録してください。ログを共有する前に認証情報を削除してください。レスポンスが文書化されたAPIエラー形式ではなくHTMLなら、その事実も残してください。一般的なエラーページからモデルの失敗を推測してはいけません。

仮の最初のクリックについて、確認すべきなのはタスクIDがあるかどうかです。サーバーに保存された送信レスポンス、該当するワークフロー出力、文書化されたコールバック記録を探してください。実際にリクエストを送ったアカウントまたはプロジェクトを確認してください。別のダッシュボードアカウントでは、この送信がジョブを作成したかどうかは判断できません。

タスクIDがある場合は、そのタスクから続ける

識別子を復元できたら、プロバイダーが文書化している読み取り操作を使用してください。reAPIでは、GET /api/v1/tasks/{id} でクレジットを消費せずにタスクを取得できます。[3] 以降の確認にはこれを使います。元の生成リクエスト本文を再送すると、別の送信が作成されます。

レスポンス内のタスク状態を読み取ってください。reAPIはタスクが見つかればHTTP 200を返します。タスクの状態が failed の場合も同じです。[4] したがって、HTTP 200は動画の成功を意味しません。同様に、照会時の500も動画の失敗を証明するものではありません。照会から利用可能な回答を得られなかったという意味です。

完了したタスクは、文書化された出力フィールドを使って処理してください。アプリが2回目の生成を待ち続けないよう、必要なファイルを保存します。処理中のタスクは引き続き確認します。失敗したタスクでは、新たな試行が妥当かどうかを判断する前に、エラーと精算情報を確認してください。

失敗したタスクとその請求は関連していますが、同じものではありません。reAPIは失敗分の返金を文書化しています。また、一部モデルでは、生成後の安全性チェックにより、課金対象の生成が行われた後に出力がブロックされる場合があります。[3] 実際のタスクの使用量記録を保存してください。一般的な「サーバーエラー」表示だけでは、すべての料金が消えるべきだとは判断できません。失敗した生成の課金処理は、終端状態のタスクと適用されるポリシーに基づいて判断します。

IDがない場合は、受理されたかどうかを未確定のままにする

より難しいのは、最初のクリックで利用できる送信レスポンスが得られなかった場合です。アプリケーションでは、その操作を明示的に未確定状態にしてください。たとえば内部値 acceptance_unknown を使うと、送信されなかった処理や、プロバイダーが失敗を確認した処理と区別できます。これはアプリケーション状態の提案であり、すべてのAPIが返すフィールドではありません。

安定したローカル操作IDを保持し、復旧の担当者を1人または1つに定めてください。担当者は、連携機能が実際に提供する証拠、つまり保存済みレスポンス、コールバック、認可されたタスク履歴、サポートチームの調査結果などを照合できます。後からタスクが特定できたら、元の操作に関連付けて、そこから続けてください。

ローカルのタスクID欄が空であることから分かるのは、アプリケーションがIDを保存しなかったことだけです。受理後にレスポンスが失われた可能性があります。同様に、ローカル操作IDがプロバイダーに自動的に伝わったり、作成エンドポイントに重複排除をさせたりするわけではありません。証拠を整理するのには役立ちますが、処理が厳密に1回実行された証拠ではありません。

Idempotency-Key ヘッダーも慎重に扱ってください。HTTP POSTは本来冪等ではなく、繰り返しの安全性はエンドポイントの実際の契約によります。[5] reAPIはこのヘッダーを記録しますが、生成リクエストの重複排除には使わないと明示しています。同じキーで受理済みPOSTを繰り返すと、別のタスクと追加料金が発生する可能性があります。[6]

証拠から結論が出ない場合でも、意図的に代替タスクを作ることが業務上の判断として妥当な場合はあります。その場合は、未確定の元タスクに関連付けられた別の試行として記録し、両方が完了する可能性を考慮してください。再試行キューを簡単にするために、最初の試行を黙って「未作成」に変更してはいけません。結果や請求が遅れて届いたときに必要となる記録が消えてしまいます。

n8nが何を再実行するか確認する

ワークフローエディターでは、同じ曖昧さを見落としがちです。「Generate Video」と表示されたノードが、処理を送信した後に結果を待つ場合があります。ノードが赤く表示されるのは待機時間が終了したためで、リモートの予測処理は続いていることがあります。

WaveSpeedの公式n8n連携ドキュメントは、まさにこの動作を説明しています。生成ノードは予測処理を送信して結果を待ちます。正のタイムアウト値を設定すると、予測処理が続いていてもノードが失敗することがあります。ドキュメントは、n8nのRetry On Failがノード全体を再実行し、別途課金される新しい予測処理を作ると警告しています。一時的なポーリング障害は、すでに内部で再試行されています。[7] この注意はこの連携に適用されるもので、すべてのコミュニティノードに自動的に当てはまるわけではありません。

HTTP Requestノードで構成したワークフローでは、再試行を設定したノードの動作を確認してください。n8nではRetry on Failはノード単位で設定されます。[8] そのノードが生成POSTを送るなら、もう一度試すと同じPOSTが再送されます。既知のタスクを読み取るだけなら、繰り返されるのは読み取りです。ワークフローに表示されたエラー文だけでは、ノードの確認に代わりません。

実用的な設計の1つは、送信とポーリングの間で受理済みタスクIDを永続化することです。そうすれば、作成処理を再度通らず、読み取り手順から復旧できます。これは上で述べた送信レスポンスの喪失には対処しません。その未確定経路は別に保持してください。実行全体を手動で再実行する場合も同様に確認が必要です。先に成功した作成ステップが再び実行されることがあるためです。

仮の二重クリックに戻ると、2回目のクリックを自動ノード再試行に置き換えても、請求の問題は変わりません。アプリケーションは、元のジョブについて問い合わせているのか、新しい動画を要求しているのかを把握する必要があります。

停止地点を決めて読み取りを再試行する

既知のタスクを読み取る際の一時的な障害は、比較的再試行しやすいケースです。同じタスク識別子を使い、エンドポイントで文書化されたポーリングとレート制限のルールに従い、許可された試行回数または経過時間の予算を使い切ったら、直ちに繰り返すループを止めてください。

AWSは、不安定な依存先への過剰な負荷を避けるため、上限付き指数バックオフ、ジッター、試行回数の制限を説明しています。[1] ジッターはすべてのクライアントの次の試行を同じ瞬間に集中させず、時間を分散します。こうした手法は再試行の負荷を管理しますが、作成POSTを重複排除される操作に変えるものではありません。

復旧を担当するレイヤーを1つ選んでください。SDK、ワークフローノード、外側のワーカーがそれぞれ独立して繰り返すと、実際の通信量が外側の設定から想定される量を超えることがあります。ループを追加する前に、連携機能に組み込まれた再試行を確認してください。

読み取り予算が尽きたら、後で照合できるようタスクIDを保持してください。クライアントの期限が示すのは、そのクライアントがどれだけ待ったかです。文書化されたキャンセル操作が成功していない限り、リモート生成が停止した証拠にはなりません。新しい処理を送信する可能性がある、無条件の「再試行」ボタンを提示するのではなく、取得結果が未確定であることを表示してください。

置き換えを選ぶ前に具体的なエラーを確認する

構造化されたエラーを取得したら、そのコードと文書化された適用範囲を確認してください。たとえばreAPIは、60001 と 60002 をタスクの永続化またはワークフロー開始に失敗したケースとして示し、クレジットを返金すると説明しています。[4] こうした明示されたケースと、内容不明のHTML 500レスポンスや送信後の接続切断では、復旧の判断が異なります。返金の扱いをすべてのサーバーエラーに広げてはいけません。

具体的なレスポンスが無効な入力や使用できないメディアを示している場合は、別の試行を送信する前に、そのエンドポイントの文書に沿って指摘された問題を修正してください。元の試行の証拠を保持し、修正後の送信は新しい処理として扱います。入力を変更しても、以前の送信が受理されたかどうかという未確定状態は解決しません。

HTTPステータスとレスポンス詳細がなければ、「サーバーは現在このリクエストを処理できません」という表示だけでも情報が不足しています。プロンプトを繰り返し変更したり、ブラウザーを更新したり、タイムアウトを延長したりしても、サーバー側のどこで障害が起きたかは特定できません。プロバイダー管理のエンドポイントでは、そのサポート窓口を通じてメソッド、URL、UTC時刻、利用可能な識別子を提示してください。reAPIのエラーガイドでは、この証拠を指定しています。[4]

別のプロバイダーが対応する入力、出力、運用条件がタスクに合うなら、代替先として役立つ場合があります。しかしホスト名が違うだけでは、障害経路が独立しているとは証明できません。また、代替先で成功しても元の送信で何が起きたかは分かりません。後から完了した元タスクも含め、両方の試行を確認できる状態にしてください。

未処理のタスクを再開する前に、すでに送信した処理を把握してください。既知のタスクは引き続き観察するか、結果を記録する必要があります。未知の送信には担当者を置き、置き換えるかどうかを明示的に判断します。最初の再試行が成功することは有用ですが、各ユーザー要求に対して存在する可能性のあるリモートジョブを説明できて初めて、復旧の経緯が理解可能になります。

参考資料

  1. AWS Builders Library:タイムアウト、再試行、ジッターを伴うバックオフ。2019年に初公開されたエンジニアリングガイダンス。副作用、有界の再試行、再試行の増幅を扱います。
  2. MDN:HTTP 500 Internal Server Error。定義とサーバー側の調査。
  3. reAPI Tasks。ポーリング、状態、出力、精算の意味。
  4. reAPI Errors。具体的な失敗コードとサポートに必要な証拠。ここでの再試行判断は、参考資料6の送信契約も適用しています。
  5. MDN:冪等。HTTPメソッドの意味と、繰り返しが安全だと仮定することの限界。
  6. reAPI API 概要。生成の送信とIdempotency-Keyの契約。
  7. WaveSpeed公式n8n連携ドキュメント。ノードのタイムアウト、ノード全体の再試行、別途課金される予測処理。2026年11月15日取得。
  8. n8n公式HTTP Request一般的な問題のドキュメント。Retry on Failとノードの再試行設定。2026年11月15日取得。
すべてのガイド