LLMゲートウェイのエラー分類：認証、クォータ、プロバイダー、安全性の障害を分離する

LLMゲートウェイのエラー分類は、制御されたインシデントと高コストなリトライの嵐との違いを生みます。ゲートウェイは、失敗したすべてのモデル呼び出しを同じ種類のプロバイダーエラーとして扱うべきではありません。無効な認証情報、使い果たされたクォータ、プロバイダーの過負荷、不正な形式のリクエスト、安全性による拒否、タイムアウト、クライアントによるキャンセルはすべて、異なる回復パスを必要とします。

よくある間違いは、すべての障害を同じリトライおよびフォールバックループに送ることです。それは失効したキーを隠蔽し、支出上限を使い果たし、安全でないコンテンツを別のプロバイダーにルーティングし、またはストリーミング応答がすでに開始された後に作業を重複させる可能性があります。実用的なLLMゲートウェイのエラー分類は、エンジニアリング、製品、財務の各チームに、何が起こったのか、そしてゲートウェイが次に何をすべきかについての一つの共通言語を提供します。

Flatkeyはこの運用モデルに適合します。なぜなら、現在の公開サイトでは、この製品をモデルアクセス、ルーティング、請求、使用状況分析、および運用管理のための単一のゲートウェイサーフェスとして位置づけているからです。その共有サーフェスを使用して、リトライ、キュー、フォールバック、またはフェイルクローズの動作を選択する前に障害を分類します。

LLMゲートウェイのエラー分類一覧表

HTTPステータスだけでなく、クラスから始めましょう。同じステータスファミリーでも、プロバイダー、SDK、エンドポイントの形状によって意味が異なる場合があります。

このLLMゲートウェイのエラー分類は、意図的にアクション指向になっています。ダッシュボード用にエラーにラベルを付けるだけではありません。システムがいつより多くのトークンを消費できるか、いつ所有者に状態の修正を依頼する必要があるか、そしていつ停止すべきかを決定します。

リトライする前に分類する

公式のプロバイダードキュメントは、これらのクラスの分離をサポートしています。OpenAIのエラーガイドは、無効な認証、不正なAPIキー、IP許可リストの失敗、レート制限、クォータまたは請求の枯渇、サーバーエラー、過負荷、SDK接続エラー、SDKタイムアウト、不正な形式のリクエスト、権限拒否、およびレート制限の例外を区別しています。そのレート制限ガイダンスは、ランダムな指数バックオフを推奨していますが、失敗したリクエストも分間制限にカウントされることに注意を促しています。

Anthropicのエラードキュメントは、invalid_request_error、authentication_error、permission_error、not_found_error、request_too_large、rate_limit_error、api_error、およびoverloaded_errorを区別しています。Anthropicはまた、retry-afterガイダンス付きの429レート制限を文書化しており、その停止理由ガイダンスには、モデルレベルの停止条件としてrefusalが含まれています。

Geminiのトラブルシューティングは、認証と権限の失敗を、429 RESOURCE_EXHAUSTED、500内部エラー、および503利用不可とは別にマッピングしています。Geminiのレート制限ドキュメントは、リクエスト、トークン、1日あたりのリクエスト、および支出のディメンションについて説明しています。Geminiの安全性設定はまた、プロンプトブロック、候補のfinishReason、およびsafetyRatingsも公開しており、応答コンテンツがブロックされた場合のfinishReasonがSAFETYになることも含まれます。

その証拠は、単純なルールにつながります。LLMゲートウェイのエラー分類は、ゲートウェイがアクションを選択する前に、プロバイダー固有のシグナルを決定フィールドに正規化する必要があります。

認証と権限の障害

認証と権限の障害は、直ちに停止する必要があります。不正なキーや禁止されたプロジェクトを再試行しても、通常は結果を変えることなくノイズが増えるだけです。

これらのシグナルを認証クラスに正規化します。

ゲートウェイでは、認証エラーに owner_key、credential_id、project_id、provider、endpoint_family、requested_model、route_id を含める必要があります。生のシークレットをログに記録することは避けてください。インシデントでは、どのキーが失敗したか、どのルートが呼び出しを試みたか、誰がそれを修正できるかを明確にする必要があります。

認証障害の場合、フォールバックは通常は間違いです。チームがあるプロバイダーを承認していない場合、黙って別のプロバイダーに切り替えると、調達、データ境界、またはモデルポリシーをバイパスする可能性があります。制御された応答とは、明確な障害、所有者への警告、そして修正パスです。

クォータとレート制限の障害

クォータとレート制限の障害は、曖昧な再試行ロジックによって最も害を受けるクラスです。429は、バーストのペーシング、1分あたりのリクエスト制限、1分あたりのトークン制限、1日あたりのリクエスト制限、月間予算の枯渇、プリペイドクレジットの枯渇、または支出ベースの制限を意味する場合があります。これらのケースは、単一の回復パスを共有しません。

クォータの決定には、このLLMゲートウェイのエラー分類を使用してください。

重要なのは、一時的なペーシングと枯渇した予算を区別することです。バックオフは、プロバイダーが速度を落とすように要求している場合に役立ちます。アカウントにクレジットがない場合や、ジョブが利用可能なトークンバジェットに収まらない場合、バックオフは役に立ちません。

より詳細な再試行チェックリストが必要な場合は、このセクションをFlatkeyのAI API再試行戦略と組み合わせてください。財務および運用部門が重複したトークン消費を確認できるように、再試行の試行をログに表示し続けてください。

プロバイダーとトランスポートの障害

プロバイダーとトランスポートの障害は、クォータの障害とは異なります。これらは、リクエストが有効で、キーが有効で、予算が利用可能であっても、ルートが呼び出しを完了できなかったことを意味します。

一般的なシグナルには次のものがあります。

ここではプロバイダーのフォールバックが役立つ場合がありますが、契約が必要です。フォールバック ルートは、エンドポイントの形状、ツール、構造化出力のニーズ、コンテキスト ウィンドウ、データ境界、モデルの承認、およびコスト上限を維持する必要があります。ストリーミングがすでに表示可能なトークンを出力している場合、より安全な動作は、別のルートからの出力をつなぎ合わせるのではなく、停止して制御された障害を示すことです。

ストリーミング固有のリカバリーにはストリーミングAI APIの信頼性を使用し、プロバイダーのエラーを自動的なルート変更に変える前にモデルのフォールバック評価を使用してください。

リクエストと検証の失敗

リクエストと検証の失敗は、通常、プロバイダーのインシデントではありません。これらは、呼び出し元がエンドポイントで処理できないものを送信したことを意味します。

例としては、必須フィールドの欠落、不正な形式のJSON、サポートされていないパラメーター、間違ったエンドポイントファミリー、無効なモデルID、長すぎるコンテキスト、サポートされていないツールスキーマ、互換性のないモダリティ、またはエンドポイントの契約を満たさないファイル/画像/動画入力などが挙げられます。

ゲートウェイはこれらのフィールドをログに記録する必要があります。

変更されていない検証の失敗を再試行しないでください。リクエストを有効な形に変換するか、修正すべきフィールド名を指定した開発者向けのエラーを返してください。ゲートウェイが複数のエンドポイントファミリーをサポートする場合、あるプロバイダーにとっては有効なリクエストが別のプロバイダーにとっては無効である可能性があるため、検証エラーは特に重要です。

安全性とポリシーの失敗

安全性とポリシーの失敗は、再試行とフォールバックが誤ってガードレールを弱める可能性があるため、独自のクラスが必要です。安全性の拒否はプロバイダーのダウンタイムではありません。モデレーションによるブロックはクォータの枯渇ではありません。ブロックされた出力は、ゲートウェイが禁止されたコンテンツを出力するルートを見つけるまでサンプリングを続ける理由にはなりません。

これらのシグナルを安全性クラスに正規化します。

実践的なルールは単純です。LLMゲートウェイのエラー分類では、安全性を回復可能なプロバイダーの停止として扱うべきではありません。フォールバックが許容されるのは、フォールバック ルートが同じかそれ以上の厳格な安全ポリシーを維持し、その目標がブロックをバイパスすることではなく、タスクの安全なバージョンを完了することである場合に限られます。

正規化されたエラーレコード

有用なLLMゲートウェイのエラー分類は、プロバイダー固有の障害を1つの永続的なレコードに変換します。

このレコードを「LLM呼び出しが失敗しました」のような単一の文字列に縮小しないでください。その文字列だけでは、キーをローテーションするか、待機するか、再チャージするか、フォールバックするか、プロンプトを修正するか、停止するかを決定するには不十分です。

シンプルなTypeScript分類器

分類器は、初日からすべてのプロバイダーの詳細を知る必要はありません。明示的なバケットと、保守的に失敗するデフォルトから始めます。

type ErrorClass =
  | "auth"
  | "quota"
  | "provider"
  | "request"
  | "safety"
  | "cancelled"
  | "unknown";

type GatewayErrorInput = {
  httpStatus?: number;
  providerErrorType?: string;
  providerErrorCode?: string;
  finishReason?: string;
  stopReason?: string;
  clientCancelled?: boolean;
  timeout?: boolean;
};

function classifyGatewayError(error: GatewayErrorInput): ErrorClass {
  const type = (error.providerErrorType || "").toLowerCase();
  const code = (error.providerErrorCode || "").toLowerCase();
  const stop = (error.stopReason || "").toLowerCase();
  const finish = (error.finishReason || "").toLowerCase();

  if (error.clientCancelled) return "cancelled";

  if (error.httpStatus === 401 || error.httpStatus === 403) return "auth";
  if (type.includes("auth") || type.includes("permission")) return "auth";
  if (code.includes("invalid_api_key") || code.includes("ip_not_authorized")) {
    return "auth";
  }

  if (error.httpStatus === 429) return "quota";
  if (type.includes("rate_limit") || code.includes("quota")) return "quota";
  if (code.includes("resource_exhausted")) return "quota";

  if (stop === "refusal" || finish === "safety") return "safety";
  if (code.includes("moderation") || code.includes("blocked")) return "safety";

  if (error.httpStatus === 400 || error.httpStatus === 422) return "request";
  if (type.includes("invalid_request") || type.includes("bad_request")) {
    return "request";
  }

  if (error.timeout) return "provider";
  if ([500, 502, 503, 504, 529].includes(error.httpStatus || 0)) {
    return "provider";
  }
  if (type.includes("overloaded") || type.includes("api_error")) {
    return "provider";
  }

  return "unknown";
}

これは出発点としてのみ使用してください。本番環境の分類器では、プロバイダー固有のマッピングをアプリケーションコード内にのみ埋め込むのではなく、設定、テストフィクスチャ、インシデントレビューで管理する必要があります。

ランブック：リトライ、キュー、フォールバック、またはフェイルクローズ

クラスが判明すると、ゲートウェイはアクションを選択できます。

この表は、LLMゲートウェイのエラー分類の運用上の中心です。ゲートウェイに対して、いつ作業を続けるのが安全で、いつ作業がリスクになるかを示します。

Flatkeyでの適用方法

この分類を、一度きりのダッシュボードプロジェクトとしてではなく、ロールアウトのチェックリストとして使用してください。

1. サポートチャット、バッチ抽出、評価ジョブ、コードアシスタントのトラフィックなど、1つのワークフローを選択します。
2. そのワークフローで許可されるエンドポイントファミリー、モデル、フォールバックルート、コスト上限を定義します。
3. プロバイダーのエラーを上記のフィールドに正規化します。
4. 認証と権限の障害を所有者に可視化し、再試行不可にします。
5. 一時的なレート制限を、クォータ、支出、日次制限の枯渇から分離します。
6. プロバイダーやモデルを変更する前に、フォールバック契約を要求します。
7. 安全性の拒否とモデレーションを、プロバイダーの停止ではなく、ポリシーの結果として扱います。
8. 再試行やフォールバックの前に、部分的な出力の状態をログに記録します。
9. より多くのワークフローに展開する前に、Flatkeyで使用状況とルートの証拠を確認します。
10. 運用担当者が現在のカタログとコスト体系を確認できるように、ランブックをFlatkeyの価格設定にリンクします。

Flatkeyの2026年7月3日の公開価格設定APIスナップショットは、45のモデル行、6つのベンダーIDを返し、openai、anthropic、gemini、image-generationなどのエンドポイントファミリーをサポートしていました。これらは日付の古いソース情報としてのみ扱ってください。モデルの可用性、価格、ルートの動作は、本番環境へのロールアウト前に再確認する必要があります。

よくある質問

LLMゲートウェイのエラー分類とは何ですか？

LLMゲートウェイのエラー分類とは、モデルプロバイダーのトラフィックに対する障害クラスを正規化したセットです。認証、クォータ、プロバイダー、リクエスト、安全性、キャンセルの障害を分離し、ゲートウェイが再試行、キューイング、フォールバック、またはフェイルクローズの動作を選択できるようにします。

すべてのLLM APIエラーを再試行しないのはなぜですか？

すべてのエラーを再試行すると、インシデントを悪化させる可能性があります。レート制限を増幅させたり、クォータが枯渇した後にさらにトークンを消費したり、認証情報の障害を隠したり、部分的な出力を重複させたり、安全ブロックをバイパスしたりする可能性があります。この分類は、実際に再試行が許可される場合を決定します。

安全性の拒否はフォールバックをトリガーすべきですか？

デフォルトではトリガーすべきではありません。安全性の拒否、モデレーションによるブロック、プロンプトのブロック、およびfinishReason: SAFETYは、ポリシーの結果として扱われるべきです。フォールバックは、より安全性の低いルートを見つけるために使用されるべきではありません。

LLMゲートウェイはクォータの障害をどのように分類すべきですか？

一時的なレートペーシングを、枯渇した支出、プリペイドクレジット、日次制限、トークン制限、プロジェクト制限から分離してください。一時的なペーシングには、有界バックオフやキューを使用できます。枯渇した予算は通常、所有者が追加のキャパシティを承認するまでフェイルクローズします。

FlatkeyはLLMゲートウェイのエラー分類にどのように役立ちますか？

Flatkeyは、モデルアクセス、ルーティング、請求、使用状況分析、運用管理のための単一のゲートウェイサーフェスをチームに提供します。これを使用して、正規化されたエラークラスを所有者のキー、エンドポイントファミリー、リクエストされたモデル、提供されたモデル、および使用状況の証拠に関連付け続けることができます。

まず1つのワークフローから始め、LLMゲートウェイのエラー分類を定義し、次にキーを取得して、本番トラフィックが自動回復に依存する前に、認証、クォータ、プロバイダー、リクエスト、安全性、キャンセルのケースをテストしてください。