AI APIエラー：401・403・429・5xx

AI APIのHTTP Statusは調査の入口であり、原因の全体ではありません。Retry前にRequest ID、UTC時刻、Endpoint、Model、Key名、選択Group、構造化Error、Timingを保存し、Client、認証、Access Policy、Protocol、Routing、Model Backend、Downstream接続のどこで終わったかを切り分けます。

Status Codeの初期判断

Status	最初の見方	最初の対応
400	PayloadまたはProtocolが不正	修正し、同じ内容を再送しない
401	Keyがない、無効、停止、期限切れ	Authorizationと現在のKeyを確認
403	Account、Model、Group、IPのPolicy	Channelより先にKey制限を確認
404	PathまたはModel IDが違う	Base URLと/v1/modelsを確認
429	Quota、Rate、Routeの制限	制限元を特定し有界Backoffを使う
499	Clientが完了前に切断	Deadline、Abort、Proxy、First Outputを確認
502/503/504	Upstream、可用性、時間予算の問題	証拠を保存し限定的にFallbackまたはRetry

Layerごとに診断する

401は通常Routing前に起きます。Authorization: Bearer ...、Keyの状態、Host、Deploymentに残る古いSecretを確認します。完全なKeyをLogやTicketへ貼らないでください。

403はProvider拒否の証明ではありません。Model Limit、IP Allowlist、Group権限、Account PolicyがChannel選択前に作用できます。同じKeyで/v1/modelsを取得し、正確なError Codeを見ます。

429ではKey、Account、Model Group、Routeのどこに制限があるかを確認します。Retry-Afterに従い、Jitter付き指数Backoffを使い、回数、総時間、Concurrencyを制限します。Keyを増やしてもAccount Limitを回避できるとは限りません。

499はDownstream接続が終了した記録です。Abort、Browser、CDN、Load Balancer、Proxyから確認し、最初の有効出力を比較します。1件だけでChannel障害とは判断できません。

Retryの判断

• 不正Request、Key、Access：原因を修正し、同じ内容を再送しない。
• Rate Limit：許可される場合のみ有界Backoff。
• 一時的な502、503、504：安全に反復できる処理だけ厳しい予算でRetry。
• Client Cancellation：結果がまだ必要で重複副作用がない場合のみ。
• ToolやWrite：Application LevelのIdempotencyを先に用意する。

各試行は新しい処理とコストを生み得ます。共有してよい証拠はID、時刻、Endpoint、Streaming、Model、Group、Status、Error Code、Timingです。完全なKey、Prompt、Response、Body、Email、平文IPは通常のLogに含めません。原因特定後はRoutingガイドとStreamingガイドを利用します。

レイヤーごとの確認事項

401の場合

Authorization: Bearer ...、余分な引用符や空白、キーの有効状態、デプロイに残った古いシークレットを確認します。通常はモデルルーティングより前に発生します。

403の場合

同じキーで許可モデル、IP許可リスト、グループアクセス、アカウントポリシーを確認します。チャネル選択前の拒否なら、プロバイダーを変えても解決しません。

429の場合

キー、アカウント、グループ、ルートのどこに制限があるか特定します。Retry-Afterに従い、揺らぎを加えた指数バックオフを使い、回数、総時間、同時実行数を制限します。

499の場合

クライアントから調べます。キャンセルシグナル、閉じたタブ、CDN、ロードバランサー、プロキシの期限を確認し、キャンセル時刻と最初の有効出力を比較します。単独の499はチャネル障害の証拠ではありません。

5xxを種類ごとに分ける

500は決定的なアダプター障害、502は無効または不完全な上流応答、503は一時的なルート不足、504は時間予算の超過を示すことがあります。元のステータスを保持し、安全な操作だけを厳しい上限付きで再試行してください。

安全に残せる診断情報

• リクエストIDとUTC時刻。
• エンドポイントとストリーミングモード。
• 指定モデルと選択グループ。
• HTTPステータスと構造化エラーコード。
• 総時間と最初の有効出力までの時間。
• クライアントがキャンセルしたかどうか。
• ツールや画像など、機能を機密情報なしで表した説明。

明示的に承認された安全な手続きでない限り、完全なキー、プロンプト、応答、元のリクエスト本文、メールアドレス、平文IPは含めません。

よくある質問

403はプロバイダー停止の証拠ですか？

いいえ。アカウント、キー、モデル、グループ、IP、機能ポリシーが、プロバイダー選択前にリクエストを拒否できます。

499は一般的な上流モデルエラーですか？

いいえ。Modelflareの記録では、応答完了前に観測された下流側キャンセルを表します。

すべての5xxを再試行すべきですか？

いいえ。安全に繰り返せる処理だけを、回数と総時間を制限して再試行し、最初のエラーを残してください。