直接回答
503 はサービスレイヤーが一時利用不可または過負荷であることを示します。全 queue の再投入ではなく低頻度 probe から復旧します。
このガイドで解決できること
service overload、maintenance、capacity 不足、circuit breaker の 503 から安全に復旧する。
症状と影響範囲を確認する
maintenance、capacity 不足、region 障害、gateway circuit breaker で 503 が返ります。
一つの model、protocol、route、region だけが失敗し、軽量 endpoint は正常な場合があります。
- 設定を変更する前に、ステータスまたは例外、レスポンス本文、request ID、UTC 時刻、クライアント版、最終ホストを保存します。
- 最小リクエストと失敗するワークフローを比較し、全体障害、モデル固有、機能固有のどれかを切り分けます。
- 認証情報、完全なプロンプト、顧客データ、非公開ファイルをスクリーンショットやサポート資料に含めません。
主な原因と責任境界
エラーは一つのレイヤーから得た証拠であり、下流全体の故障を証明するものではありません。まず次の可能性を順に検証します。
- model service または gateway に利用可能 capacity がない。
- maintenance、deployment、regional dependency により instance が一時的に外れている。
- upstream failure 後に circuit breaker が traffic を拒否している。
- queue と同期 retry が部分復旧後も過負荷を継続させている。
レイヤー別に最小診断を行う
可変要素が最も少ないリクエストから開始します。アカウント、API ホスト、対象モデルは維持し、任意機能だけを外します。
一度に一項目だけ変更し、元のステータス、ヘッダー、本文、所要時間を残します。これによりクライアントのシリアライズとゲートウェイ・上流の挙動を分離できます。
- 01境界を確定高い同時実行を止め、低頻度 health probe だけを残します。
- 02基準を作成Retry-After、status message、request ID、UTC 時刻を記録します。
- 03一項目を比較platform、protocol、model、account、region を比較し影響範囲を決めます。
- 04決定的な証拠を記録全 backlog ではなく単一 request から段階的に戻します。
date -u
curl -sS -D /tmp/api-503.headers -o /tmp/api-503.body -w '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-503.headers
確認した根本原因に修正を適用する
証拠で確定したレイヤーだけを最小限変更します。決定的な設定エラーを広範な再試行や検証無効化で隠さないでください。
- 01障害レイヤーを修正復旧情報を守り、上限付き queue と jitter backoff を使います。
- 02必要な動作を復元互換性を確認した正常な代替先にだけ route します。
- 03一時回避策を除去health と latency の安定後に積み残しを分割して処理します。
一度の成功ではなく修正結果を検証する
最小確認が成功したら元の経路を再実行し、通常のストリーミング、同時実行数、タイムアウト条件でも安定することを確認します。
- 軽量 health check が継続して成功する。
- 低 traffic で最小生成が安定する。
- 各増量段階で latency と error rate が制御される。
- backlog が circuit breaker 付きの小分けで解放される。
セキュリティ境界とエスカレーション資料
認証、通信、権限、検証を弱めず、かつ機密情報を公開しない範囲で、再現とエスカレーションに必要な証拠を収集します。
- 機密 traffic を未承認の緊急 provider へ送らない。
- task state で external action の重複を防ぐ。
- client-facing error に内部 incident 情報を出しすぎない。
- 影響範囲、時刻、request ID、recovery header、probe 結果で共有する。
公式情報と検証範囲
本ガイドはプロトコル仕様とクライアント公式文書を根拠にしています。エラー文、再試行ヘッダー、設定項目はサービスやバージョンで変わるため、参照元を確認し、ログとリクエスト例を秘匿してから共有してください。
技術検証方法を見る