Cloudflare AI Gateway がプロバイダーの資格情報エラーを HTTP 401 に統一 — Google Vertex は 500＋リトライから 401（リトライなし）へ
Cloudflare が AI Gateway の REST API で、プロバイダー側が資格情報を拒否したときのエラー応答を標準化した。POST /ai/run は大半のケースで HTTP 401・エラーコード 2009 を返し、Unified Billing でプロバイダーが拒否した場合は HTTP 503 を返す。従来はプロバイダーごとにばらついており、ElevenLabs は 403（UserCredentialsError）、Google Vertex は 500 を返してリトライが走り、その他は 402 や独自コードだった。これらが 401 に集約される。公式は「HTTP 401 をプロバイダー資格情報の無効または拒否として扱うこと」と明記している。Google Vertex で 500 を一時障害としてリトライしていた実装は、挙動が変わるため見直しが必要になる。
ニュース原文を読む ↗要約
Cloudflare が AI Gateway の REST API で、プロバイダー側が資格情報を拒否したときのエラー応答を標準化しました。
AI Gateway は、複数の AI プロバイダーへの呼び出しを1か所に集約するための前段です。 OpenAI、Google Vertex、ElevenLabs などへのリクエストを Gateway 経由で投げ、ログ、キャッシュ、レート制御をまとめて扱えます。ところが、エラー応答はプロバイダーのものがそのまま通っていました。
どれくらいばらついていたかというと、同じ「資格情報が拒否された」という状態に対して、こうでした。 ElevenLabs はプロバイダー固有の UserCredentialsError で 403、Google Vertex は 500、その他のプロバイダーは 402 や独自コード。
これが実装側に何を強制するかというと、プロバイダーごとのエラー解釈です。 Gateway を使って「プロバイダーを抽象化する」はずなのに、エラーハンドリングだけは抽象化されていなかったことになります。
今回の変更で、POST /ai/run の応答は2つに整理されました。 大半の資格情報拒否は HTTP 401・エラーコード 2009。 Unified Billing を使っていてプロバイダーが拒否した場合は HTTP 503。
公式は開発者向けのアクションとして、「AI Gateway REST API のエラーを扱うアプリケーションは、HTTP 401 を『プロバイダー資格情報が無効または拒否された』として扱うこと」と明記しています。
既存実装にとって、もっとも注意すべきは Google Vertex です。 従来は 500 を返し、リトライが走っていました。 これが 401（リトライなし） に変わります。つまり**「一時障害として再試行されていたものが、即座に失敗として返る」**ということです。
これは改善ですが、挙動の変化です。 500 を一時障害として扱うのは正しいリトライ設計です。しかし資格情報の誤りに対してリトライするのは、無駄な待ち時間とリクエストを生むだけです。 401 で即座に返るなら、設定ミスに早く気づけます。 一方で、「リトライで吸収されていたエラー」が表面化するため、切り替え直後にエラー率が上がって見える可能性があります。
まとめると、Gateway の抽象化がエラー層まで広がったという変更です。 地味ですが、マルチプロバイダー構成を実運用している組織には、コードが減る種類の変更です。
何が変わったか
- AI Gateway REST API（
POST /ai/run）のプロバイダー資格情報エラーが標準化された（2026-10-06 の changelog エントリ） - 大半の資格情報拒否は HTTP 401・エラーコード 2009 を返す
- Unified Billing でプロバイダーが資格情報を拒否した場合は HTTP 503 を返す
- 従来の挙動
- ElevenLabs: プロバイダー固有の
UserCredentialsError（403）→ 401 - Google Vertex: 500 を返しリトライが走る → 401（リトライなし）
- その他のプロバイダー: 402 や独自コード → 401
- ElevenLabs: プロバイダー固有の
- 公式の指示: 「HTTP 401 をプロバイダー資格情報の無効または拒否として扱うこと」
業務インパクト（一般企業向け）
最初にやることは、エラーコードで分岐しているコードの棚卸しです。
AI Gateway を経由している実装で、ステータスコードを条件に使っている箇所を探してください。特に次の3つです。(1) 403 を ElevenLabs の資格情報エラーとして扱っている分岐、(2) 500 をリトライ対象にしている設定、(3) 402 を課金エラーとして扱っている分岐。いずれも 401 に変わるため、分岐が機能しなくなります。
(2) のリトライ設定が、実務上もっとも影響が大きいです。 Google Vertex の資格情報エラーが 500 からリトライされていた構成では、資格情報の設定ミスが「遅いけど最終的にエラー」として現れていました。 これが即座のエラーに変わります。デバッグは楽になりますが、監視のしきい値は見直しが必要です。 リトライで吸収されていたぶん、エラー率のグラフが跳ねて見える可能性があります。
監視・アラートの設定変更を忘れないでください。 401 を「クライアント側の問題だから無視」として扱っている監視設定があると、資格情報の失効に気づけなくなります。 AI Gateway 経由の 401 は、自社の API キーが失効したか、プロバイダー側が拒否したかのサインです。これはアラートを上げるべきエラーです。 通常の Web API の 401（利用者の認証失敗）とは意味が違うので、同じルールで扱わないでください。
Unified Billing を使っている場合は 503 の扱いを決めてください。 503 は一般に一時障害を意味するため、リトライ対象に入っている実装が多いはずです。 しかし資格情報の拒否が原因なら、リトライしても解決しません。 Unified Billing を使っているなら、503 のうち資格情報由来のものを識別して、リトライから除外するか、少なくともリトライ回数を絞る設計が必要です。公式は 503 の詳細な識別方法を書いていないため、ここは実装で確認してください。
ドキュメントの更新対象になります。 社内の運用手順書に「AI Gateway が 500 を返すときはプロバイダー側の障害」と書いてあるなら、それは誤りになりました。 障害対応の一次切り分けに使う文書は、優先して直してください。切り分けを間違えると、設定ミスを障害として調査することになります。
副業・個人活用視点
この種の変更は、保守案件の価値を示す材料になります。
「エラーコードが変わった」という変更は、動いているシステムを静かに壊します。 機能追加ではないので誰も見ていませんが、リトライ設定やエラー分岐が噛み合わなくなると、障害対応のときに初めて気づきます。変更を追っていて先に直せる人は、保守契約の価値を証明できます。
具体的な提案の形にしやすいです。 「AI Gateway のエラーコードが統一されました。現在 Vertex の 500 をリトライ対象にしているので、設定を見直します。あわせて 401 のアラートを追加します」——これは1〜2時間の作業で、効果が説明できる仕事です。 継続契約の中で成果を見せる材料として、ちょうどよい粒度です。
マルチプロバイダー構成を自分で組んでいる人には、コードが減ります。 プロバイダーごとにエラーを解釈していた分岐を、401 の1本に畳めます。 個人開発では、こういう「減らせる場所」を見つけて実際に減らすのが、長く動かし続けるコツです。書いたコードの量が、将来の自分の保守コストです。
注意点として、「401 ならリトライしない」を機械的に入れないでください。 AI Gateway 経由の 401 は資格情報の問題ですが、Gateway を使わずプロバイダーを直叩きしている箇所が混在している場合、401 の意味が違います。 コードベースに両方ある状態で統一ルールを入れると、別の場所が壊れます。 棚卸しを先にやってください。
記事にするなら、「リトライで隠れていたエラーが表面化する」という点を書くと価値があります。 公式の changelog は「401 として扱ってください」とだけ書いています。その結果として監視のグラフが変わる、という運用側の影響は書かれていません。 実際に切り替えてエラー率の変化を測った記事は、同じ構成を運用している人に確実に読まれます。