AI API のエラーと再試行:重複作業を防ぐ
再試行すべき故障と修正すべきリクエストを分け、非同期タスクの二重作成を防ぎます。

繰り返す前に原因を読む
不正なリクエスト、無効なキー、未対応のパラメータは、同じ内容を再送するより設定を直す必要があります。レート制限や一時的な障害は仕様に従って再試行できる場合があります。ステータスとリクエスト ID は残し、秘密情報や機密プロンプトはログに記録しません。
認証や権限エラーではキーとアクセスを確認します。形式、モデル名、パラメータの誤りでは要求を修正します。レート制限や一時的な障害は文書に従って再試行できる場合があります。すべてを「ネットワークエラー」と呼ぶと手掛かりが失われ、無意味な再送につながります。
一時的な障害には回復の時間を
再試行できる場合は回数を制限し、待機時間を延ばしながらランダムなばらつきを加えます。サーバーが待機時間を示すなら尊重し、全体の期限も設けます。すべてのエラーを一律に再試行せず、大量のクライアントが同時に再送しないようにします。
文書が再試行を認めるエラーには、回数と全体時間の上限を設け、待機を徐々に長くしてランダムなばらつきを加えます。サーバーが明示的な待機時間を返す場合は尊重します。利用者がキャンセルできるようにし、上限に達したらバックグラウンドで無期限に続けず終了します。
一時的な障害では、待機してから制御された方法で再試行する。副作用のある処理に注意
タイムアウト時点で遠隔側が既にリクエストを受け付けていることがあります。画像や動画タスクを再作成すると、処理や費用が重複する可能性があります。返されたタスク ID を保存し、再送前に状態を確認します。冪等性は API が明記している場合にだけ利用します。
送信後のタイムアウトは、遠隔でタスクが作成された後に応答だけ失われた可能性があります。ID を受け取ったら保存して照会し、受け取れなくてもタスクがないと決めつけません。検索、コールバック、冪等性が文書化されているか確認し、復旧手順に従います。新規作成前に追加費用の可能性を伝えます。
待っている人に次の一歩を伝える
再試行、入力の修正、後での再訪のどれが必要かを伝えます。途中までのストリーミング文章は必要に応じて残し、未完了だと示します。不正入力、レート制限、通信切断、遅いタスクをそれぞれ試し、全部を同じ曖昧なメッセージにしないようにします。
時刻、リクエスト ID、エンドポイント、状態、経過時間、必要なエラー分類があれば調査を始められることが多いです。完全なキー、認証ヘッダー、不要なプロンプトは記録せず、共有前に個人情報を確認します。利用者には次の操作を、保守担当者には追跡可能で限定された情報を示します。
無効なパラメータ、認証失敗、レート制限、切断、遅い非同期タスクを別々に再現します。適切なエラーだけを再試行し、待機に上限があり、必要なら途中結果を残すことを確認します。再試行の連打でタスクが重複しないかも試します。実際の顧客データや本番の有料タスクは不要です。
まず失敗の種類を見分ける
状態コード、リクエスト ID、時刻、機密を除いたエラーを残します。認証ならキーや権限、入力エラーなら要求形式を修正します。制限や一時的な障害は後で再試行できる場合がありますが、実際の応答と文書に従い、すべてを同じ再送ループへ入れないでください。
通信がタイムアウトしても、遠端が要求を受け取っていないとは限りません。送信後に応答だけ失われた場合、処理が進行中または完了している可能性があります。タスク作成やデータ変更では、重複実行と費用に関わる重要な違いです。
利用者には入力が保持されているか、後で再試行できるかを分かりやすく示します。キー、内部 URL、スタック全体は表示せず、調査用のリクエスト ID を案内します。
再試行の回数と時間を制限する
一時的なエラーには、最大回数と総待機時間を設け、試行に応じて間隔を長くする方法があります。ランダムな揺らぎを加えると、多数のクライアントが同時に再送するのを抑えられます。応答が待機時間を指示する場合は、API の規則を優先します。
ブラウザ、アプリ、ライブラリがそれぞれ再試行すると回数が予想以上に増えます。どの層が担当するかを決め、結果を記録します。上限に達したら停止し、いつまでも読み込み表示を続けずに次の行動を示します。
書き込みや作成には、サービスが実際に提供する重複防止の仕組みを使うか、既知のタスク状態を先に確認します。任意の API が特定の冪等キーに対応すると決めつけず、不確実な場合はユーザーに伝えます。
二つの失敗で動作を検証する
テキスト要求が制限された場合、入力を保持し、許された待機時間と上限の範囲で復旧を試せます。待機中に取り消せるようにし、上限を超えたら完了できなかったことを明示します。
動画生成の送信後、ID を受け取る前に通信が切れた場合は、作成済みかどうか分かりません。API が対応する照会や復旧を試し、確認できない場合はその不確実性を説明します。裏で複数回作成せず、再生成の費用は実際の規則を確認します。
無効キー、パラメータ不備、切断、取消も自動テストに加え、各層の試行回数、通知、ログを確認します。一時的な失敗ごとに重大アラートを出すと重要な問題が埋もれるため、影響範囲と継続時間で区別しましょう。
異なる二つの失敗
レート制限で再試行までの時間が返された場合は、回数と全体時間の上限内でその指示に従います。動画作成の送信後にタイムアウトした場合、タスクが既に存在する可能性があります。保存済み ID があれば先に状態を確認します。ID がなければ不確実さを伝え、無料で再送できると決めつけず文書に従います。
問い合わせには時刻、モデル名、リクエスト ID、脱敏済みのエラー説明を用意します。公開の場所でキーや完全な私的内容を求めてはいけません。安全な再試行を案内する前に、既にタスクが作成されていないか確認します。