症状からトラブルシューティング：z-request-id で 401 / 502 / ストリーム断を特定

StackOverflow で頻出する質問：「プロキシを通したらストリーミングのレスポンスが 1 つの塊になった」「ツール呼び出しの JSON が組み立たない」「この 429 はレート制限かクォータ超過か」「この 502 はゲートウェイかベンダーか」。

AI 呼び出しのトラブルシューティングは難しいものです。多段の経路、ストリーミング、一貫しないエラーコード。何かが壊れたとき、どのホップか分かりません。

GateLLM は各リクエストに z-request-id を付与し、ログ全体を通します。症状から特定できます。401 / 403 → 認証と Header ACL、404 → ルーティング、502 / 503 → アップストリームの健全性、タイムアウト → レート制限と越境、ストリーム断 → バッファリングと SSE、OOM → 設定。

エラーコードは正規化され（クロスベンダーのエラーセマンティクスを統一）、ストリーミングはバッファリングせずネイティブに通し、Token Ops のログは照会・エクスポートできます。