直接回答
500 は応答サービス内部で生成されますが、特定 model や任意機能が引き金の場合もあります。再試行前に request を縮小します。
このガイドで解決できること
一時的な上流障害、機能固有の server bug、gateway の 500 を安全に分離する。
OpenAI 互換 APIPython / Node.js SDKcurlリバースプロキシと API ゲートウェイ
01
症状と影響範囲を確認する
接続後に構造化または plain な HTTP 500 が返り、断続的または一つの機能だけで発生します。
最小 text request や別 model は成功しても、tools、image、structured output、長い context で失敗します。
- 設定を変更する前に、ステータスまたは例外、レスポンス本文、request ID、UTC 時刻、クライアント版、最終ホストを保存します。
- 最小リクエストと失敗するワークフローを比較し、全体障害、モデル固有、機能固有のどれかを切り分けます。
- 認証情報、完全なプロンプト、顧客データ、非公開ファイルをスクリーンショットやサポート資料に含めません。
02
主な原因と責任境界
エラーは一つのレイヤーから得た証拠であり、下流全体の故障を証明するものではありません。まず次の可能性を順に検証します。
- gateway、model service、依存先で一時的な内部障害が発生している。
- 未対応または不正な高度機能が未処理の server path に到達している。
- 一つの model deployment だけが異常で別 route は正常。
- 無制限 retry が部分障害を増幅している。
03
レイヤー別に最小診断を行う
可変要素が最も少ないリクエストから開始します。アカウント、API ホスト、対象モデルは維持し、任意機能だけを外します。
一度に一項目だけ変更し、元のステータス、ヘッダー、本文、所要時間を残します。これによりクライアントのシリアライズとゲートウェイ・上流の挙動を分離できます。
- 01境界を確定応答 host、Content-Type、request ID、UTC 時刻を特定します。
- 02基準を作成tools、image、format、stream、長い context を外します。
- 03一項目を比較同じ host・account で既知の正常 model と比較します。
- 04決定的な証拠を記録error rate 上昇時は batch を止め、機密除去した再現を一件保存します。
最小診断コマンド言語：bash
date -u
curl -sS -D /tmp/api-500.headers -o /tmp/api-500.body -w 'status=%{http_code} total=%{time_total}
' 'https://<your-api-host>/v1/models' -H "Authorization: Bearer ${API_KEY:?set API_KEY first}"
04
確認した根本原因に修正を適用する
証拠で確定したレイヤーだけを最小限変更します。決定的な設定エラーを広範な再試行や検証無効化で隠さないでください。
- 01障害レイヤーを修正再実行安全な request だけを上限付き exponential backoff で retry します。
- 02必要な動作を復元サービス側の対応確認まで、特定した引き金を無効化または修正します。
- 03一時回避策を除去能力、cost、data policy が許容できる場合のみ検証済み fallback model を使います。
05
一度の成功ではなく修正結果を検証する
最小確認が成功したら元の経路を再実行し、通常のストリーミング、同時実行数、タイムアウト条件でも安定することを確認します。
- 再実行安全な request のみが上限内で retry される。
- 高度な項目を一つずつ戻し引き金を確定した。
- fallback の能力と cost 境界が明示されている。
- 元 model が同じ 500 なしで連続成功する。
06
セキュリティ境界とエスカレーション資料
認証、通信、権限、検証を弱めず、かつ機密情報を公開しない範囲で、再現とエスカレーションに必要な証拠を収集します。
- 曖昧な失敗後に tool action や外部 write を盲目的に再実行しない。
- 再現 request の本文を共有前に機密除去する。
- request を通すため検証を無効化しない。
- request ID、model、endpoint、時刻、最小 payload で共有する。
公式情報と検証範囲
本ガイドはプロトコル仕様とクライアント公式文書を根拠にしています。エラー文、再試行ヘッダー、設定項目はサービスやバージョンで変わるため、参照元を確認し、ログとリクエスト例を秘匿してから共有してください。
技術検証方法を見る