直接回答
502 は proxy または gateway が有効な upstream response を取得できなかった状態です。header と本文から生成レイヤーを特定します。
このガイドで解決できること
HTTP 502 を返す reverse proxy と upstream 接続障害を解決する。
症状と影響範囲を確認する
有効な model response より前に CDN、ingress、reverse proxy、application gateway が 502 を返します。
モデル一覧は成功しても、別 upstream path、timeout、buffering を使う生成や streaming が失敗します。
- 設定を変更する前に、ステータスまたは例外、レスポンス本文、request ID、UTC 時刻、クライアント版、最終ホストを保存します。
- 最小リクエストと失敗するワークフローを比較し、全体障害、モデル固有、機能固有のどれかを切り分けます。
- 認証情報、完全なプロンプト、顧客データ、非公開ファイルをスクリーンショットやサポート資料に含めません。
主な原因と責任境界
エラーは一つのレイヤーから得た証拠であり、下流全体の故障を証明するものではありません。まず次の可能性を順に検証します。
- upstream host、port、protocol、DNS、SNI、Host header が誤っている。
- upstream が再利用 connection を閉じた、または proxy timeout を超えた。
- proxy と upstream 間で TLS・certificate name 検証が失敗している。
- stream response が buffer、compress、truncate され無効扱いになる。
レイヤー別に最小診断を行う
可変要素が最も少ないリクエストから開始します。アカウント、API ホスト、対象モデルは維持し、任意機能だけを外します。
一度に一項目だけ変更し、元のステータス、ヘッダー、本文、所要時間を残します。これによりクライアントのシリアライズとゲートウェイ・上流の挙動を分離できます。
- 01境界を確定header、brand 付き HTML、request ID から 502 生成レイヤーを特定します。
- 02基準を作成軽量なモデル一覧と最小 non-stream request を試します。
- 03一項目を比較non-stream の基準が安定してから streaming を試します。
- 04決定的な証拠を記録UTC 時刻、connection metadata、request ID で gateway と upstream log を関連付けます。
curl -sS -D /tmp/api-502.headers -o /tmp/api-502.body -w 'remote=%{remote_ip} status=%{http_code} total=%{time_total}
' 'https://<your-api-host>/v1/models' -H "Authorization: Bearer ${API_KEY:?set API_KEY first}"
sed -n '1,30p' /tmp/api-502.headers
確認した根本原因に修正を適用する
証拠で確定したレイヤーだけを最小限変更します。決定的な設定エラーを広範な再試行や検証無効化で隠さないでください。
- 01障害レイヤーを修正upstream protocol、host、port、DNS、SNI、Host を一致させます。
- 02必要な動作を復元connection lifetime、connect/read/idle timeout を調整します。
- 03一時回避策を除去TLS 検証を維持しつつ不適切な SSE buffering を無効化します。
一度の成功ではなく修正結果を検証する
最小確認が成功したら元の経路を再実行し、通常のストリーミング、同時実行数、タイムアウト条件でも安定することを確認します。
- upstream identity と transport 設定が実サービスと一致する。
- connection pool と timeout budget が制御負荷で安定する。
- SSE event が buffer・truncate なしで逐次通過する。
- bounded retry、circuit breaker、request ID、metric が有効である。
セキュリティ境界とエスカレーション資料
認証、通信、権限、検証を弱めず、かつ機密情報を公開しない範囲で、再現とエスカレーションに必要な証拠を収集します。
- 恒久対応として upstream TLS 検証を無効化しない。
- 非公開 upstream address と header を外部報告に含めない。
- proxy trust と forwarded header を制限する。
- 機密除去した response header、時刻、request ID、両レイヤーの状態で共有する。
公式情報と検証範囲
本ガイドはプロトコル仕様とクライアント公式文書を根拠にしています。エラー文、再試行ヘッダー、設定項目はサービスやバージョンで変わるため、参照元を確認し、ログとリクエスト例を秘匿してから共有してください。
技術検証方法を見る