Skip to main content
失敗した Router 呼び出しには、HTTP ステータス、X-Comfy-Error-Type に入るエラーバケット、X-Comfy-Request-Id に入るリクエスト ID が含まれます。再試行するかどうかを判断する前に、これら 3 つすべてと、送信した Idempotency-Key を保存しておいてください。

エラーを防御的に読み取る

失敗したリクエストは、プロキシの HTML エラーページ、切り詰められた JSON、またはプレーンテキストを返すことがあります。JSON パースエラーによって HTTP ステータスやリクエスト ID が隠れてしまわないようにしてください。これらのヘルパーは Python では httpx.Response を、TypeScript では Fetch の Response を使用します。SDK はノーマルな SDK 呼び出し向けのエラーフィールドをすでに公開しています。

検証エラー

Router の 422 は、プロバイダーの呼び出し前に検証に失敗したことを意味し、課金されません。そのボディには detail[] 配列があり、拒否されたフィールドごとに 1 つのエントリが含まれます。エラーカテゴリはボディではなく X-Comfy-Error-Type にあります。例えば:
これはあくまで形状の例です。寛容な入力スキーマを持つモデルは、Router の 422 を返す代わりに、不足しているフィールドをプロバイダーに転送することがあります。 400 は、このフィールド単位の検証ボディではなく、不正なカーソルなどのリクエストレベルの問題を表します。エラーリファレンスにサポートされているカテゴリの一覧があります。不明なカテゴリは制御フロー上は internal_error として扱いますが、診断用にオリジナルの値は保持してください。新しいエラー値をハード拒否したり、予測されるエラーカテゴリがあたかも既に発生しているかのように実装したりしないでください。

安全に再試行する

モデル ID とリクエストボディとともに、キーを送信する前に永続化してください。その論理呼び出しのすべての試行で同じキーを再利用します。Router はレスポンスで Idempotency-Key を返しません。Python SDK は送出する例外にキーを含めます。TypeScript では、指定したキーを自分で保持してください。 キーは、認証情報が伴うワークスペース内で共有されるか、ワークスペースを伴わない場合はユーザーにスコープされます。そのスコープ内で一意の UUID を使用し、同じ認証情報で再試行してください。別のワークスペースメンバーのキーを再利用すると、そのメンバーの記録済み結果が返されたり、競合が発生したりする可能性があります。認証情報を変更すると、別の課金対象の呼び出しが開始される可能性があります。 Router はキー付きのレスポンスまたはコレクションの状態を 24 時間保持します。再試行によって新しい保持ウィンドウが開始されることはありません。その状態が期限切れになった後は、古いキーで結果を復元したり、新しいディスパッチを防いだりできるとは期待しないでください。また、キーを使用しても、期限切れのアセット URL が再び使用可能になることはありません。

再試行の結果

競合は、方法、モデルパス、クエリ、ボディを比較します。キーは、サイズ超過の応答、失敗した応答の書き込み、または安全に再生できないアセットの後に、再生不能になることがあります。待機しても、消費済みの結果は復旧しません。新しいキーは新しい呼び出しを開始します。古い出力を取得するものではありません。 プロバイダーへのディスパッチ前の拒否は、キーを解放します。ディスパッチされた呼び出しは、プロバイダーのハンドルを保持したり、再生不能になったりすることがあります。ステータスコードだけからキーの状態や課金を推測しないでください。 呼び出しがタイムアウトした、あるいは接続が切断されたというだけで、まったく新しいキーを発行しないでください。Router がすでに生成を受け付けていた場合、新しいキーは 2 つ目の論理的な実行を作成し、したがって 2 回目の課金対象の結果を生む可能性があります。オリジナルの呼び出しが復旧不能であると判明するまで、同じキーを再利用してください。

タイムアウトと収集

Router の呼び出し 1 回は、デフォルトで 10 分間接続を保持することがあります。クライアントのタイムアウトはその上限より長く設定してください。そうすることで、不透明なローカル abort ではなく、型付きの 504 とリクエスト ID を取得できます。アプリケーションがそれほど長く接続を保持できない場合、キュー中の配信 が request_id を即座に返し、後で結果を収集できます。 deadline_exceeded は Router の待機上限であり、provider_timeout はプロバイダーの期限です。完了したプロバイダーの生成は、呼び出し元がタイムアウトを受け取ったか切断された場合でも課金されることがあります。クライアントのキャンセルは待機と SDK のリトライを停止しますが、受け入れられたプロバイダーの処理を必ずしもキャンセルするわけではありません。 送信とポーリングを行うプロバイダーでは、保持されたハンドルにより、同じキーのリクエストがオリジナルの生成の収集を続けることができます。復元可能なハンドルなしで途切れたディスパッチ済みの呼び出しは、再生可能な結果を残さずにキーを消費する可能性があり、その場合、同じキーでのリトライは 409 を返します。成功が捕捉されていないプロバイダー起因の一時的な障害では、別の試行のためにキーを解放できる場合もあります。ハンドルが存在しないことだけでは、どちらの結果が当てはまるかは分かりません。 SDK は一部の失敗を限られた予算内でリトライします。エラーが返されたら、新しいリクエストやキーを生成するのではなく、そのリクエストとキーを保持してください。生の HTTP の場合、次の例では 2 つの明示的な収集ヒントのみをリトライします:
オリジナルのモデル、ボディ、保存したキーを渡してください。これは試行回数を制限するもので、合計の実時間を制限するものではありません。各呼び出しはクライアントのタイムアウトまで続く可能性があり、各待機は Retry-After に従います。HTTP エラーは検査用にレスポンスを保持し、トランスポートエラーはキーを置き換えずに伝播します。アプリケーションがより長いリカバリウィンドウを必要とする場合は、保存したキーで後での収集をスケジュールしてください。

次のステップ

  • 請求: 拒否、タイムアウト、リプレイにかかるコスト。
  • ヘッダー: 冪等性、リクエスト ID、リトライ間隔のヘッダー。
  • API リファレンス: Router が返すすべてのエラーバケット。