GuidesOneMux

OpenAI APIの認証・レート制限・タイムアウト・不正レスポンスを安全に診断する方法

認証、リクエスト制限、タイムアウト、不正なレスポンスなどのOpenAI APIエラーを、認証情報やユーザーデータを漏らさず診断するための実践的なガイドです。

AI

要約 · TL;DR

OpenAI APIの障害を安全に調査するには、再試行する前にエラーの種類を判別します。認証エラーは通常、キー、組織、プロジェクト、IPの設定を修正する必要があります。レート制限やクォータのエラーには、リクエスト間隔の調整や管理上の変更が必要です。タイムアウトは一時的な場合があります。不正なレスポンスは、通信、プロキシ、解析の問題として切り分けます。認証情報やユーザーの生データではなく、診断に必要なメタデータを記録しましょう。

要点

  • 401認証エラーや請求・クォータのエラーを、一時的なネットワークエラーのように再試行しないでください。
  • 429のスロットリングや503の過負荷では、Retry-Afterがあれば従い、上限付きの指数バックオフを適用します。
  • APIキーをソースコード、ログ、例外メッセージ、クライアント側アプリケーションに含めないでください。
  • JSON以外のレスポンスやJSON解析の失敗は、通信またはプロキシの問題として切り分け、診断情報はマスキングして長さを制限します。
  • 問題が続いてエスカレーションする際は、モデル、エラーコード、タイムスタンプ、タイムゾーン、サニタイズしたリクエスト詳細を提示します。
目次 (7)

OpenAI APIの障害は、設定エラー、処理能力の問題、ネットワーク障害、レスポンス解析の失敗に分けると解決しやすくなります。最初に考えるべきなのは、再試行すれば結果が変わる可能性があるかです。

401は、再試行しても通常は改善しません。リクエスト頻度が原因の429は、間隔を調整すれば改善する場合があります。一方、クレジットの枯渇や支出上限が原因の429には、アカウントまたはプロジェクトの変更が必要です。タイムアウトは一時的なこともありますが、繰り返し発生する場合は、ネットワーク、プロキシ、リクエストサイズに問題がある可能性があります。

以下の手順では、JavaScriptと、OpenAIのエラーコードガイドで説明されている公式OpenAIライブラリの概念を使用します。コードは実装例であり、本番環境でテスト済みの統合ではありません。

デバッグを始める前に:認証情報とユーザーデータを保護する

エラーを再現する前に、次の対策を行ってください。

  • APIキーは、サーバー側のシークレットマネージャーまたは環境変数に保存します。ブラウザーのコード、モバイルアプリ、ソース管理、サポートチケットには絶対に含めないでください。
  • リクエストのタイムスタンプ、エンドポイントのカテゴリ、モデル識別子、HTTPステータス、取得できる場合は構造化されたエラーコードを記録します。
  • Authorizationヘッダー、リクエスト本文全体、レスポンス本文の生データ、個人データを含むプロンプトを記録しないでください。
  • 診断にプロンプトが必要な場合は、元のテキストではなく、マスキングしたサンプルか、内部で一意に識別できるリクエストIDを記録します。
  • 診断用データの長さを制限します。プロキシから大きなHTMLエラーページが返る場合や、上流のエラーに保存するつもりのなかったデータが含まれる場合があります。

運用上の有用な原則は、ログで何が、どこで失敗したかは分かるようにしつつ、ユーザーが何を入力したかや認証方法は記録しないことです。

まず401認証エラーを診断する

ドキュメントに記載された401の原因には、認証の無効化、APIキーの誤り、組織への所属不足、許可されていないIPアドレスがあります。403は、サポート対象外の国、地域、または領土を示す場合があります。

次の順に確認してください。

  1. サーバーが意図したシークレットを読み込んでいること、その値が途中で切れていないこと、期限切れ、失効、置き換えが発生していないことを確認します。
  2. リクエストが意図したAPIエンドポイントとプロジェクトに送信されていることを確認します。
  3. 組織IDやIP許可リストを使用している場合は、どちらもプロジェクトの設定と照合します。
  4. 開発環境、コンテナ、ホスティング環境で、異なる外向きIPアドレスからリクエストが送信されていないか確認します。
  5. ログを共有する前に、デバッグ出力から認証情報を取り除きます。

401や403に対して自動再試行を行わないでください。同じ無効な認証情報で再試行すると、ログが増えるうえ、インシデントの分析が複雑になることがあります。設定を修正してから、新しいリクエストを送信してください。

429のスロットリングとクォータ・請求の問題を切り分ける

429がすべて「すぐに再試行すればよい」という意味ではありません。OpenAIのガイドでは、次のようなケースを区別しています。

エラーの種類対応の目安自動再試行するか
レート制限に到達リクエスト間隔を調整し、Retry-Afterがあれば従う上限を設けて行う
slow_downリクエスト頻度を下げ、徐々に戻す慎重に行う
クレジット残高の枯渇クレジットを追加するしない
組織またはプロジェクトの支出上限該当する上限を変更するしない
組織の使用量上限承認済みの上限引き上げを申請するか、サポートに連絡するしない

再試行ループでは、すべての429を同じものとして扱わず、HTTPステータスと具体的なエラーコードを確認してください。最大試行回数を設定し、指数バックオフとジッターを使用して、複数のワーカーが同時に再試行しないようにします。Retry-Afterがある場合は、独自に設定した最大待機時間の範囲内で、その値を優先してください。

503レスポンスも考慮に入れてください。参照元のドキュメントでは、モデルの過負荷はserver_is_overloadedとして示されており、再試行前にRetry-Afterがあれば従うことを推奨しています。Pythonライブラリでは、過負荷がInternalServerErrorとして、429レスポンスがRateLimitErrorとして表される場合があります。過負荷が常に429で返されるとは限らないため、その前提でハンドラーを実装しないでください。

タイムアウトと接続エラーを調査する

公式Pythonライブラリでは、タイムアウトしたリクエストにAPITimeoutError、接続の問題にAPIConnectionErrorが定義されています。調査時に確認すべき主なポイントは次のとおりです。

  • レスポンスが返る前のタイムアウト: クライアントのタイムアウト設定、ネットワーク経路、プロキシ、ファイアウォール、リクエストサイズを確認します。
  • 接続エラー: DNS、TLS証明書、外向きのファイアウォールルール、プロキシ設定を確認します。
  • サーバー側エラーの繰り返し: サービスのステータスページを確認し、サポートに問い合わせるためのサニタイズ済みタイムスタンプを保存します。

タイムアウトが発生しても、サーバーがリクエストを処理していないとは限りません。重複処理が問題になる操作では、たとえば操作を独自のリクエスト記録と関連付けるなど、再試行後も安全に照合できるようアプリケーションを設計してください。タイムアウトを際限なく延長したり、上限なく再試行したりして問題を解決しようとしないでください。

コンテンツを漏らさず不正なレスポンスに対処する

「不正なレスポンス」は、いくつかの異なる問題を指す場合があります。不正なリクエストによるBadRequestError、期待するスキーマに一致しないレスポンス、あるいはJSONの代わりにプロキシから返されたHTMLや途中で切れたデータなどです。OpenAIのガイドでは、BadRequestErrorは不正または不完全なリクエストとして説明されており、必須パラメーター、エンコーディング、形式、サイズの確認が推奨されています。

生のHTTPクライアントやミドルウェアでは、次の項目を個別に確認してください。

  1. 解析する前にHTTPステータスとContent-Typeを確認します。
  2. ガード付きのブロック内でJSONを解析します。
  3. 使用する前に、必須フィールドが存在することを検証します。
  4. ポリシーで許可されている場合に限り、ステータス、Content-Type、レスポンスの長さ、マスキングして長さを制限した抜粋だけを記録します。
  5. 解析エラーメッセージにAPIキー、プロンプト全体、レスポンス全体を含めないでください。

次のようなラッパーが例として考えられます。

async function parseSafeResponse(response) {
  const contentType = response.headers.get("content-type") || "";
  const body = await response.text();

  if (!contentType.toLowerCase().includes("application/json")) {
    throw new Error(`Unexpected response type: ${contentType}; length=${body.length}`);
  }

  try {
    return JSON.parse(body);
  } catch {
    throw new Error(`Invalid JSON response; length=${body.length}`);
  }
}

この例では、意図的にエラーとしてスローする際に本文を含めていません。本番環境では、エンドポイントに応じたスキーマ検証を追加し、生のペイロードは管理された、プライバシー審査済みの診断プロセスでのみ保持してください。

プライバシーに配慮したエラーハンドラーのパターン

公式JavaScriptの例では、接続エラー、レート制限エラー、その他のAPIエラーを区別しています。この考え方を拡張し、シークレットやユーザー入力を出力せずにエラーを分類します。

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

try {
  const response = await client.responses.create({
    model: process.env.OPENAI_MODEL,
    input: "Redacted diagnostic input"
  });

  console.log({ ok: true, hasOutput: Boolean(response.output_text) });
} catch (error) {
  const details = {
    name: error?.name,
    status: error?.status,
    code: error?.code
  };

  if (error instanceof OpenAI.AuthenticationError) {
    console.error("Authentication failed", details);
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error("Rate limit or quota response", details);
  } else if (error instanceof OpenAI.APIConnectionError) {
    console.error("Connection failed", details);
  } else if (error instanceof OpenAI.APIError) {
    console.error("OpenAI API error", details);
  } else {
    console.error("Unexpected local error", { name: details.name });
  }
}

デプロイするSDKのバージョンに応じて、クラス名とエンドポイントの動作を確認してください。プロバイダー互換のエンドポイントが、SDKのすべてのパラメーターやレスポンスフィールドに対応しているとは限りません。

問題をエスカレーションする場合

問題が続く場合、OpenAIのガイドでは、モデル、エラーメッセージとコード、リクエストデータとヘッダー、タイムスタンプ、タイムゾーン、その他の関連情報を提供することが推奨されています。提出前に内容をサニタイズしてください。認証情報を置き換え、Cookieを削除し、個人データをマスキングし、可能な場合はリクエスト本文を要約します。公開フォーラムに機密情報を投稿しないでください。

実際の対応はシンプルです。認証やクォータの問題は設定を修正し、スロットリングや過負荷にはバックオフを適用し、タイムアウトはネットワークの境界を調べ、プライベートなペイロードを保持せずに解析エラーを切り分けます。

よくある質問

OpenAIの429レスポンスはすべて再試行すべきですか?

いいえ。リクエスト頻度やslow-downが原因の場合は、慎重にバックオフし、`Retry-After`があれば従って再試行します。クレジットの枯渇、支出上限、組織の使用量上限は、再試行しても解決しません。

OpenAIの過負荷エラーが429ではなく503で返ることがあるのはなぜですか?

OpenAIのエラーガイドでは、モデルの過負荷は`server_is_overloaded`コードを伴う503として説明されています。過負荷が常にレート制限のレスポンスになるとは限らないため、エラーハンドラーではステータスとコードの両方を確認してください。

OpenAIの認証エラーについて、何をログに記録すべきですか?

タイムスタンプ、環境、エンドポイントのカテゴリ、ステータス、サニタイズ済みのエラーコードを記録します。APIキー、Authorizationヘッダー、リクエスト本文全体、ユーザーのプロンプトの生データは記録しないでください。

無効なJSONレスポンスはどのように調査しますか?

解析前にHTTPステータスとContent-Typeを確認し、ポリシーで許可される場合に限って、長さを制限しマスキングした診断情報を取得します。また、HTMLの返却、データの切り詰め、レスポンスの変更が起きていないか、プロキシやミドルウェアを調査してください。

関連記事