エラーと復旧手順

一般的な HTTP エラーと SDK の例外については、共通のエラーコードガイドを参照してください。

エラーの確認方法

リクエストが失敗した場合は、HTTP レスポンスを確認してください。ターンの実行中や環境のセットアップ中に失敗した場合は、イベントと保存済みの状態を確認してください。

構造化されたエラーでは、アプリケーション内の判定に error.code を使い、失敗の理由を説明するには error.message を使います。リクエストの検証エラーでは、error.param から修正すべきフィールドを特定できる場合があります。未知のコードを受け取った場合や param がない場合でも、エラーハンドラーが正常に動作するようにしてください。

ベータ版 API（OpenAI-Beta: agents=v1）では、セッションの error はメッセージ文字列または null です。セッションが失敗したときのエラーコードは、失敗に伴って送られる SSE の error イベントで確認してください。

API リクエストのエラー

これらは Agents API へのリクエストに関するエラーです。処理開始後に返されるターンのエラーとは区別されます。

Files API のレート制限

セッションの作成やファイルの添付をリクエストすると、HTTP 429 とともに files_api_rate_limit_exceeded が返される場合があります。Agents API は Files API を通じてファイルを確認します。この確認は、認証済みユーザーの Files API 利用枠を消費します。添付ファイルごとに個別の確認が必要になる場合があります。

12345678{
  "error": {
    "type": "rate_limit_error",
    "code": "files_api_rate_limit_exceeded",
    "message": "The Files API rate limit for your user has been exceeded. Reduce the rate of requests that access files, then try again.",
    "param": null
  }
}

ファイルに同時にアクセスするリクエスト数を減らしてください。再試行には指数バックオフを使用し、試行回数に上限を設けてください。すぐに再試行すると、利用枠を使い切った状態が続く可能性があります。

この HTTP レスポンスは、リクエストした操作が失敗したことを示します。作成成功のレスポンスが返された後で、セッションやターンが非同期に失敗する場合とは異なります。このエラーの判定には、メッセージ本文の照合ではなく error.code を使用してください。

ターンのエラー

失敗したターンでは status: "failed" となり、error に code と message が含まれます。たとえば、モデルが過負荷状態になると、次のエラーが返されることがあります。

1234{
  "code": "server_overloaded",
  "message": "The model is temporarily overloaded. Please retry your request after a brief delay."
}

ターンのエラーコードには、固有の HTTP ステータスはありません。たとえば、過負荷でターンが失敗した場合は server_overloaded が使われますが、HTTP レスポンスでは server_is_overloaded が使われることがあります。

セッションと環境のエラー

ターンが失敗しても、セッションまで失敗したとは限りません。セッションを取得し、続行できるかどうかを確認してください。status が requires_action の場合は、必要なアクションを実行してください。セッションが失敗した場合は、原因を解消し、引き続き必要な入力を指定して新しいセッションを作成してください。

復旧手順

一時的な障害時の再試行

レート制限、過負荷、タイムアウト、一時的なサービス障害が発生した場合は、次の手順に従ってください。入力が無効な場合や、認証情報または請求額の上限に問題がある場合は、原因を解消してから再試行してください。

1. 処理結果を確認します。 セッションが作成されている場合は、そのセッション、ターン、保存済みの項目を取得してください。ターンがまだ実行中であれば、引き続き進行状況を確認してください。完了していれば、その結果を使用してください。
2. 実行済みの操作を確認します。 ターンが失敗していても、すでにファイルが変更されたり、外部ツールが呼び出されたりしている可能性があります。エージェントに同じ作業を依頼する前に、これらの操作の影響を確認してください。
3. 再試行には間隔と上限を設けます。 共通の再試行ガイドに従い、HTTP レスポンスの Retry-After が指定する待機時間を守ってください。試行回数の上限または再試行の期限も設定してください。
4. リクエストを再試行するか、新しいターンを開始します。 HTTP エラーの場合は、元の操作の結果を確認してから、その操作を再試行してください。ターンが失敗した場合は、セッションが idle になるまで待ち、追加のメッセージを送信して、未完了の作業だけを続けるよう依頼してください。既存の会話を引き継いで新しいターンが始まります。

ターンが完了した場合も、ツールの実行結果を確認してください。エラーが変わった場合や再試行回数が上限に達した場合は、自動再試行を停止してください。

無効な入力の修正

error.param または error.message が示すフィールドを修正してから再送信してください。

サイズに関するエラーの場合は、入力と出力スキーマまたはツールの実行結果のサイズを小さくしてから再試行してください。エージェントの設定が大きすぎる場合は、指示とツール定義を短くして、新しいセッションを作成してください。

アップロードの要件と例については、アップロードエラーの解決方法を参照してください。メッセージが画像の問題を示している場合は、画像データまたは URL を確認してください。

ストリーム切断時の対処

error イベントを受信した場合やストリームが切断された場合、それだけではターンの最終状態を判断できません。切断されたストリームの復旧手順に従って再接続し、保存済みの作業内容を確認してから入力を再送信してください。取得したセッションが status: "failed" の場合、または agent.session.failed を受信した場合は、再接続を中止し、セッションの復旧手順に従ってください。

エラーが解消しない場合は、サポートへの問い合わせにリクエスト ID、セッション ID、ターン ID を記載してください。