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ガイドを利用します。