AI API エラーガイド:401、403、429、5xx の診断
AI API の認証、アクセスポリシー、レート制限、クライアントのキャンセル、サービス提供元の障害を切り分けて診断し、安全に再試行できるタイミングを判断します。

AI API のエラーは、ステータスコードを原因そのものではなく、調査の出発点として扱うと診断しやすくなります。再試行する前に、リクエスト ID、タイムスタンプ、エンドポイント、モデル、API キー名、選択されたグループ、レスポンスボディ、タイミングを記録しておいてください。
目的は、リクエストを拒否した、または終了させたのがどのレイヤーかを特定することです。対象となるレイヤーは、クライアント、認証、アクセスポリシー、プロトコルの検証、ルーティング、モデルバックエンド、ダウンストリームの接続です。
主なステータスコードが示す一般的な意味
| ステータス | 最初に考えられる原因 | 最初に取る対応 |
|---|---|---|
| 400 | リクエストの形式、フィールド、プロトコルの仕様が無効 | 選択したエンドポイントとペイロードを比較する。変更せずに再試行しない |
| 401 | 認証情報がない、形式が正しくない、無効化されている、期限切れ、または無効 | Authorization ヘッダーと現在のキーを確認する |
| 403 | 認証済みだが、アカウント、モデル、グループ、IP、ポリシーによってブロックされている | チャネルを調べる前に、キーの制限とモデル・グループへのアクセス権を確認する |
| 404 | エンドポイントのパスが誤っている、またはモデル ID が利用できない | Base URL、パス、認証済みのモデル一覧を確認する |
| 429 | リクエストレート、クォータ、または利用可能なルートの上限 | クォータとグループの上限を調べる。上限付きのバックオフか、設定済みのフォールバックを使う |
| 499 | 完了前にダウンストリームのクライアントが切断またはキャンセルした | クライアントの期限、中止処理、プロキシ、最初の出力までの時間を調べる |
| 500 | 内部処理またはアダプターの障害 | リクエスト ID を記録する。処理を繰り返しても安全な場合のみ再試行する |
| 502/503 | サービス提供元からの不正なレスポンス、利用できないルート、または一時的なキャパシティ不足 | ルートの根拠を確認し、上限付きのフォールバックまたは再試行を使う |
| 504 | ゲートウェイまたはサービス提供元の制限時間を超過した | 最初の出力までの時間と合計時間を、クライアントの期限と比較する |
これらの解釈は診断の出発点です。個々の呼び出しで実際に何が原因だったかは、エラーボディとリクエスト記録によって決まります。
モデルを変更する前に 401 を診断する
401 は通常、実質的なモデルのルーティングが行われる前に発生します。次の点を確認してください。
- ヘッダーが Authorization: Bearer ... の形式になっている
- アプリケーションが、引用符、空白、プレースホルダーの値を含めていない
- キーが有効で、期限切れになっていない
- リクエストが、意図した Modelflare のホストに送信されている
- シークレットマネージャーやデプロイ環境に、ローテーション前の古いキーが残っていない
キー全体をログやサポートへのメッセージに貼り付けないでください。漏えいの可能性がある場合は、専用のテストキーで再現したうえで、漏えいした認証情報を失効させてください。
403 はまずアクセスポリシーの失敗として診断する
403 は、サービス提供元がリクエストを拒否したことを自動的に意味するものではありません。認証に成功しても、チャネルが選択される前に、次の理由でアクセスが拒否されることがあります。
- キーが、リクエストされたモデルを制限している
- キーの IP 許可リストに、観測されたクライアント IP が含まれていない
- アカウントが、選択されたモデルグループを利用できない
- ユーザーまたはキーが、ポリシーによって無効化されている
- リクエストされた機能が、そのルートでは許可されていない
同じキーで /v1/models を取得し、そのグループとモデル制限を確認したうえで、正確なエラーコードを比較してください。チャネルが選択されていない場合、サービス提供元のチャネルを変更しても、それより前の段階で下されたポリシー判断は解決できません。
再試行の集中を招かずに 429 を診断する
429 はキャパシティまたはポリシーを示すシグナルであり、短い間隔のループですぐに再試行せよという指示ではありません。その上限が、キーのクォータ、アカウント、モデルグループ、選択されたルートのどれに属するものかを特定してください。
再試行可能なレート制限の場合:
- Retry-After が返された場合は、それに従う
- ジッター付きの指数バックオフを使う
- 試行回数と合計経過時間に上限を設ける
- アプリケーションの同時実行数を、把握している範囲内に収める
- 順序付きのフォールバックグループは、リクエストしたモデルとプロトコルを維持できる場合にのみ使う
API キーを増やしても、アカウント単位やグループ単位のリクエスト上限を回避できるとは限りません。
499 は呼び出し元から順に診断する
Modelflare は、レスポンスが完了する前にダウンストリームのクライアント接続が終了した場合、499 を記録することがあります。まず呼び出し元から確認します。
- 中止シグナルが発行されましたか?
- クライアント、ロードバランサー、CDN、リバースプロキシが、アイドルタイムアウトまたは全体のタイムアウトに達しましたか?
- ユーザーがページを閉じたり、エージェントを停止したりしましたか?
- ストリームが、可視テキストを含まないツールイベントを生成しましたか?
- 最初の有効な出力までに、どれくらいの時間がかかりましたか?
499 の記録だけでは、チャネルの障害とは断定できません。ルーティングポリシーを変更する前に、同じ時間帯にある同じモデル・グループのほかのリクエストと比較してください。
5xx の失敗をレイヤーごとに切り分ける
5xx の場合は、クライアントですべての失敗を一般的な 500 に変換するのではなく、元のステータスとエラーの詳細を保持してください。
- 検証やアダプターに起因する 500 は決定的な場合があり、変更せずに再送すると再び失敗することがあります。
- 502 は、サービス提供元からのレスポンスが無効または不完全であることを示している場合があります。
- 503 は、条件を満たすルートがないか、一時的に利用できないことを示している場合があります。
- 504 は制限時間を超過したことを示しますが、どのレイヤーが原因かは別途特定する必要があります。
単発の不正なレスポンスと継続的なルートの問題を見分けるには、リクエストのタイミング、選択されたグループ、サポートが確認できるチャネルの根拠、前後のリクエストを活用してください。
再試行するかどうかを判断する
| 失敗の種類 | 再試行の基本方針 |
|---|---|
| 無効なペイロードまたは非対応のプロトコル | リクエストを修正する。変更せずに再試行しない |
| 無効なキーまたはアクセスの拒否 | 認証情報またはポリシーを修正する。変更せずに再試行しない |
| クォータの枯渇 | 意図してクォータを増やすか再配分する。ループさせない |
| レート制限 | 許可されている場合は、上限付きのバックオフで再試行する |
| 一時的な 502/503/504 | 冪等な処理に限り、試行回数を厳しく制限して再試行する |
| クライアントによるキャンセル | ユーザーがまだ結果を必要としていて、重複しても安全な場合のみ再試行する |
| ツールや書き込みの副作用 | 繰り返す前に、アプリケーションレベルの冪等性を必須にする |
再試行は新たな処理を生み、新たなコストが発生することもあります。すべての試行を記録し、後の成功によって元の失敗が見えなくならないようにしてください。
安全に記録すべき根拠
サポートへの問い合わせやインシデントのレビューに備えて、次の情報を記録します。
- リクエスト ID と UTC のタイムスタンプ
- エンドポイントとストリーミングモード
- リクエストしたモデルと選択されたグループ
- HTTP ステータスと構造化されたエラーコード
- 合計時間と、最初の有効な出力までの時間
- 呼び出し元がキャンセルしたかどうか
- ツールや画像入力など、リクエストで使用した機能について、機密情報を除いた説明
API キー全体、プロンプト、レスポンスの内容、生のリクエストボディ、メールアドレス、平文の IP アドレスは、承認された安全な手順で特に必要とされない限り、含めないでください。
障害が起きているレイヤーを特定したら、フォールバックの設計については信頼性の高い AI API ルーティングを、イベントやタイムアウトに関する失敗についてはストリーミングガイドを参照してください。
よくある質問
403 は、プロバイダーがダウンしていることの証明になりますか?
いいえ。403 は、サービス提供元のルートが選択される前に、アカウント、キー、モデル、グループ、IP、機能のポリシーによって返されることがあります。まずリクエスト記録とエラーコードを確認してください。
499 は、サービス提供元のモデルが返す標準的なエラーですか?
いいえ。Modelflare のリクエスト記録では、完了前に検知されたダウンストリーム側のキャンセルを表します。モデルの障害とみなす前に、呼び出し元とプロキシの期限を調べてください。
5xx のレスポンスはすべて再試行すべきですか?
いいえ。繰り返しても安全な処理だけを再試行し、試行回数と時間に上限を設け、最初のエラーを保持してください。アダプターやリクエストに起因する決定的な問題は、繰り返しても改善しません。