LiteLLM経由のLLM呼び出しが失敗したら、再試行を増やす前に、ゲートウェイ側で止まったのか、接続先プロバイダーのエラーを返しているのかを確認します。HTTP 429や401だけでは、直すべき設定や担当者は決まりません。応答本文とヘッダーを同じ要求に結び付けるところから始めます。
この記事は、公式資料に基づくLiteLLM AI Gatewayの通常のLLM APIルートに対する診断手順です。非ストリーミングのエラー応答を対象とし、Python SDK単体や管理API、配信途中のエラーは扱いません。実API・認証・課金の操作検証は行っていません。以下のログ断片と担当分けは架空例です。
目次
最初に失敗一件の情報を揃える
利用者の「AIが動かない」という報告だけでは、アプリの入力、接続先、LiteLLM、プロバイダーのどこを調べるか決められません。失敗した要求の時刻と呼び出し先を確認し、次を一組で残します。
表は横にスクロールできます
| 項目 | 記録するもの |
|---|---|
| 対象 | 環境、要求したモデル名、APIルート、LiteLLMの利用版 |
| HTTP | 実際のステータス、応答のContent-Type |
| 本文 | errorのmessage・type・param・code。存在しない項目は欠落として記録 |
| ヘッダー | x-litellm-call-id、待機や制限の情報があればその値 |
| アプリ側 | SDK、再試行設定、同じ業務要求を識別する内部ID |
APIキー、Authorization、顧客の質問全文は、この確認表へ貼りません。エラーメッセージ自体にキーの一部や組織情報が含まれる場合もあるため、共有前に内容を見ます。原記録を参照できる場所と、担当者へ渡す抜粋を分けてください。
error.typeだけで発生元を決めない
公式Error Referenceは、LLM APIルートのエラーをトップレベルの error オブジェクトで説明しています。type は大まかな分類で、プロバイダー由来ではnullの場合もあります。code は文字列で、HTTPステータスと同じ値とは限りません。本文の一項目だけを数値へ変換して判定せず、実際のHTTPステータスも保持します。
x-litellm-call-id があれば、ゲートウェイのログと応答を結び付ける手掛かりになります。認証の早い段階など、IDが付かない場合もあるため、欠落だけをログ障害の証拠にはしません。LiteLLM：Error Reference（新しいタブで開く）
messageの内側にあるプロバイダー名を読む
公式の診断資料は、messageに含まれる OpenAIException、AnthropicException、BedrockException などをプロバイダー由来の手掛かりとして示しています。先頭にLiteLLMの例外名が付いていることだけで、LiteLLM内部の不具合と判断しないでください。
たとえば次は形式を説明する架空の断片です。実際の応答を再現したものではありません。
HTTP 429
error.message:
litellm.RateLimitError: ... OpenAIException - Rate limit reached ...
この形なら、まずプロバイダー側の制限に対応する記録を調べる方向です。「LiteLLM経由だからLiteLLMの予算上限」とは決めません。
逆に、公式はプロバイダー名のないLiteLLMの auth_error をゲートウェイの仮想キーに関する例として示しています。アプリがLiteLLMへ渡すキーと、ゲートウェイがプロバイダーへ使う資格情報は別の確認対象です。LiteLLM：Diagnosing Errors（新しいタブで開く）
ただし、共有用ログでmessageの途中を省いていたり、前段のプロキシが本文を書き換えていたりする場合、見えていない名前を「存在しない」とは言えません。分類に必要な記録が欠けるときは発生元未確定として残し、許可されたログから確認します。
429は予算・要求量・ルーティングを分ける
同じ429でも、ゲートウェイの予算上限、送信量の制限、候補デプロイメントの状態では、確認先が違います。公式は budget_exceeded、制限関連ヘッダー、No deployments available for selected model というルーティングのmessageを区別しています。throttling_error はプロバイダー由来でも使われるため、そのtypeだけでは分けられません。
次は架空の記録を整理した例です。表の情報がそのまま実環境の原因を証明するわけではありません。
表は横にスクロールできます
| ケース | 観測した断片 | 次に調べるもの |
|---|---|---|
| A | 429、budget_exceeded、予算超過のmessage | 対象キーやチーム等の予算管理範囲 |
| B | 429、throttling_error、rate_limit_typeとreset_at | ゲートウェイ側で超過した制限の種類 |
| C | 429、OpenAIExceptionを含む制限message | プロバイダー側の対象モデル・制限 |
| D | 429、No deployments available for selected model | ルーティング先の利用可能状態と失敗履歴 |
予算超過を短い間隔の再送で解消しようとしたり、プロバイダーの制限をゲートウェイの予算変更で直そうとしたりしないための整理です。資料のヘッダー説明は利用版と照合し、ヘッダーが見えないという理由だけで発生元を確定しません。
fallbackが全滅した応答は、最後の失敗だけを見ない
Error Referenceは、再試行とfallbackを使い切ると元の例外を返し、messageへ試行履歴を追加すると説明しています。公式の例では、最初のモデル群が500、fallback先が503で失敗した場合、返るステータスは500です。
この挙動を知らずに「503が返っていないのでfallback先は調べなくてよい」とすると、調査対象を落とします。逆に、messageにfallback先のエラーがあるからといって、HTTPステータスもその値だったと書き換えません。
架空の整理メモなら、次のように別々に残します。
利用者へ返ったHTTPステータス: 500
最初のモデル群の失敗: 500
fallback先の失敗: 503
業務の最終結果: 回答を完成できず
これは状態の対応を読む例で、fallbackの設定や実行を行った記録ではありません。履歴が応答へ出ない設定なら、表示された断片だけで全経路を補完せず、管理担当者が対応するログを確認します。
担当者へ渡す判断と、未確認を残す
切り分けの成果物は「429だった」という一行ではなく、どの層を調べるか、その根拠、まだ分からないことです。次の形にすると、設定変更を急がず引き継げます。
対象環境と利用版:
発生時刻と内部要求ID:
返ったHTTPステータス:
message/type/codeの抜粋:
call IDなど確認できた対応情報:
発生元の判断と根拠:
不足している記録:
確認を依頼する担当と項目:
対象環境の設定を確認できなければ、その欄は未確認とします。権限のない人がキーを再発行したり、上限を上げたりすることを、診断完了の条件にはしません。
再開方法を決める際も、SDK、ゲートウェイ、ジョブの再試行が重なっていないかを確認します。外部ツールによる送信や更新を含む業務では、LLMが失敗したことから外部操作も未実行とは断定せず、その状態を別に照合してください。
確認した公式情報
資料確認日：2026年10月21日。応答形式とヘッダーは、利用しているLiteLLMの版、ルート、前段プロキシの設定に合わせて確認してください。