GuidesOneMux

再現可能で上限を設けたテスト計画でOpenAI APIの障害を診断する

認証、レート制限、タイムアウト、不正なレスポンスによるOpenAI APIの障害を切り分け、無制限の再試行や費用の増加を避けながら再テストする実践的な方法を紹介します。

AI

要約 · TL;DR

再現可能なOpenAI APIのチェックでは、各ケースのステータス、エラーコード、経過時間、レスポンスの構造を記録します。一時的な障害に限って上限付きで再試行し、認証、クォータ、リクエストのエラーは再試行で解決しようとせず、原因を修正します。

要点

  • HTTPステータスだけでなく、具体的なエラーコードも使って障害を特定します。
  • 一時的なレート制限やサーバーエラーは、試行回数と時間の上限内で再試行します。認証エラーやクレジットの枯渇は、一時的な問題として再試行しないでください。
  • HTTPリクエストの成功や有効なJSONとは別に、レスポンスの構造もテストします。
  • 小規模で再現可能なテストケースを用意し、各障害の再現に必要な条件を記録します。
目次 (6)

上限を設けて原因を切り分ける

OpenAI APIの呼び出しが失敗したら、まず問題がアクセス、リクエスト量、処理時間、返されたデータのどれに関係するのかを判断します。問題の種類によって、認証情報の変更、トラフィックの抑制、再試行、アプリケーションのパース処理の検証など、取るべき対応が変わります。429だけでは対処法を判断できません。一時的なレート制限の場合もあれば、支出やクレジットの上限に達しており、再試行しても解決しない場合もあります。

OpenAIのエラーコードガイドでは、APIのエラーコードと、それに対応するPythonライブラリの例外型が説明されています。実際に受け取ったレスポンスを解釈する際の参考にしてください:OpenAI APIのエラーコード。

よくある4種類の障害を切り分ける

症状まず確認すること次の対応
401認証エラーAPIキーは有効で、アクティブですか?意図した組織を使用していますか?APIキーまたは組織を修正します。該当する場合は、プロジェクトの権限とIP許可リストも確認します。
429レスポンス具体的なエラーコードとRetry-Afterヘッダーを確認します。レート制限の場合はリクエストの送信ペースを調整します。クレジットの枯渇、支出上限、使用量上限の場合は、再試行する前に該当する制限を解消します。
タイムアウトまたは接続エラーリクエストのタイムアウトと接続失敗を区別します。経過時間とネットワークの状態を記録します。適切であれば、少し待ってから慎重に再試行します。接続エラーの場合は、プロキシ、証明書、ファイアウォールのルールを調査します。
HTTPリクエストは成功したが、結果を利用できない本文をパースできるか、アプリケーションが必要とするフィールドが存在し、期待される型になっているかを確認します。フィールドの欠落や不正な値は、アプリケーションレベルのレスポンス検証エラーとして扱います。自動的にAPIの認証エラーやレート制限エラーと判断しないでください。

OpenAIのガイドによると、認証情報が無効な場合は401となります。また、リクエストレート、クレジットの枯渇、組織またはプロジェクトの制限など、複数の異なる原因で429が発生します。レート制限については、Retry-Afterがある場合はその指示に従うよう案内されています。請求、支出、クォータに関するエラーは該当する制限への対応が必要です。再試行を繰り返してもアクセスは回復しません。また、ガイドではPythonライブラリの例外として、APITimeoutErrorとAPIConnectionErrorが別々に挙げられています。出典:OpenAIのエラーコード。

小規模な評価を再現可能にする

場当たり的なプロンプトを繰り返し送信するのではなく、固定したテストケースを使います。まずは一度に1つの条件だけを検証するケースから始めましょう。

  1. ベースライン: 小さく、妥当性が確認された入力を送り、期待するレスポンスフィールドが存在することを確認します。
  2. 認証チェック: 意図したプロジェクトの認証情報を使い、同じベースラインを実行します。実際のAPIキーをログやテストレポートに誤って記録しないでください。
  3. リクエスト検証: テスト環境で許可される場合は、制御されたテストで必須パラメーターを省略するか、誤った値を指定します。結果のステータスとメッセージを記録し、不正なリクエストがすべて同じように失敗すると決めつけないでください。
  4. レート制限への対応: Retry-Afterヘッダーを含む、モックの429レスポンスを使って再試行ロジックをテストします。制限を発生させるために実際のトラフィックを送るのは避けてください。
  5. タイムアウトへの対応: クライアントまたはテストハーネスでタイムアウトをシミュレートします。遅いテストエンドポイントや本番環境へのリクエストの繰り返しは、不要な負荷や判断しにくい結果につながる可能性があります。
  6. レスポンス検証: 必須フィールドがない有効なJSON、型が異なるフィールド、不正なJSONをテストします。これらはそれぞれ別のパーサーまたは契約上のエラーです。

各ケースについて、タイムスタンプとタイムゾーン、エンドポイントまたは操作、モデル、取得できる場合はHTTPステータス、エラーの種類とコード、試行回数、経過時間、マスキングしたリクエストIDまたは診断情報を記録します。共有ログに認証情報や機密性の高い入力を保存しないでください。問題が継続しOpenAIサポートに問い合わせる場合、ガイドでは、モデル、エラーとコード、リクエストデータとヘッダー、タイムスタンプとタイムゾーン、その他の関連情報を共有するよう推奨しています。共有前に、シークレットや機密情報をマスキングしてください。

再試行に明確な上限を設ける

再試行が有効なのは、障害が自然に解消する可能性がある場合に限られます。失敗を返すまでにアプリケーションが試行できる回数と、処理に費やす合計時間の上限を定めます。レート制限のレスポンスでは、Retry-Afterが指定されていればそれに従い、再試行の回数や時間に上限を設けます。サーバーエラーについて、ガイドは少し待ってから再試行することを推奨しています。問題が続く場合は、ステータスページを確認するか、エスカレーションしてください。401、不正なリクエスト、クレジットの枯渇は、自動再試行ループを行う理由にはなりません。

Pythonでは、公式ライブラリはAuthenticationError、BadRequestError、RateLimitError、APITimeoutError、InternalServerErrorなどの例外を区別します。インストール済みのライブラリバージョンで利用できる例外クラスを処理し、取得できる場合はステータスとエラーコードを記録してください。以下の例は説明用であり、分類方法を示すものです。テスト済みの設定や、あらゆる状況に適用できる再試行ポリシーを示すものではありません。

from openai import OpenAI

client = OpenAI()  # Supply credentials using your approved secret-management method.

try:
    response = client.responses.create(
        model="YOUR_SUPPORTED_MODEL",
        input="Return the word ready."
    )
    text = response.output_text
    if not isinstance(text, str) or not text.strip():
        raise ValueError("Response text is missing or empty")
    print(text)
except Exception as exc:
    # In production, classify known SDK exceptions explicitly and log
    # status/code when available. Do not log credentials or sensitive input.
    print(type(exc).__name__, str(exc))

モデルのプレースホルダーは、プロジェクトで利用可能なモデルに置き換えてください。この例は、特定のモデル、パラメーター、プロバイダーのエンドポイントが、利用環境でサポートされていることを示すものではありません。互換性のある別のプロバイダーを使用する場合は、同じ動作を前提とする前に、そのエンドポイントとパラメーターのサポート状況がクライアント設定と一致することを確認してください。

不正なレスポンスをAPIエラーと区別する

HTTPステータスが有効でも、アプリケーションが期待する内容を受け取れたとは限りません。レスポンスの境界で検証し、パースが成功すること、必須フィールドが存在すること、値の型が利用可能であることを確認します。機密性の高いレスポンス内容をそのまま出力せず、「output_textがない」「文字列が必要」といった、検証失敗の簡潔な説明をログに記録します。

APIが構造化されたエラーを返した場合は、そのステータスとコードを診断情報に残します。リクエストが成功しているものの、独自のパーサーが本文を拒否した場合は、別の問題として記録します。これにより、APIアクセスやレート制限、リクエストの構築、通信、アプリケーション側の想定のどこを調べるべきかが明確になります。

まとめ

有用なOpenAI API評価は、小規模で再現可能、かつ上限が明確です。ベースライン、目的を絞った障害ケース、明示的な出力チェック、固定の再試行上限を用意します。各障害の再現に必要な情報を記録し、次の対応を決める際はHTTPステータスだけでなく、具体的なエラーコードを確認してください。

よくある質問

OpenAIの429エラーはすべて再試行すべきですか?

いいえ。具体的なエラーコードを確認してください。一時的なリクエストレート制限の場合は送信ペースの調整や`Retry-After`への対応が必要になることがあります。クレジットの枯渇、支出上限、使用量上限の場合は、再試行する前に該当する制限を解消する必要があります。

APIの障害と不正なレスポンスはどう見分けられますか?

HTTPステータスとAPIエラーコードを、アプリケーションによる検証結果とは分けて記録します。レスポンスが成功しても、パースできない、または必須フィールドがない場合は、APIエラーとは限らず、レスポンス検証の問題です。

障害が続く場合、どのような情報を記録すべきですか?

モデル、エラーメッセージとコード、リクエストの状況と関連ヘッダー、タイムゾーン付きのタイムスタンプ、試行回数、経過時間を記録します。ログやサポートに共有する情報からは、APIキーや機密データをマスキングしてください。

本番環境に影響を与えずにレート制限をテストするにはどうすればよいですか?

`Retry-After`ヘッダーをシミュレートしたものも含め、モックの429レスポンスで再試行の動作をテストします。レート制限を発生させるために、本番プロジェクトへ意図的に大量のリクエストを送るのは避けてください。

関連記事