Skip to content
← リリースに戻る · 2.1.267
改善 / v2.1.267

ゲートウェイの429フェイルオーバー廃止

CHANGELOG 原文（英語）

Gateway: Changed forward_user_identity upstreams to return a 429 as-is to a developer whose email was forwarded, instead of failing over to the next upstream, so the proxy's per-user limits hold
公式の変更履歴を開く ↗

日本語での補足

forward_user_identityのアップストリームで、メールが転送された開発者に対し次のアップストリームへフェイルオーバーする代わりに429をそのまま返すように変更。プロキシのユーザー単位の上限を維持

ドキュメント

自分が運用するプロキシ向けのユーザー単位の識別ヘッダー 全文を読む（英語原文） →

ドキュメントの抜粋（参考訳）

自分が運用するプロキシ向けのユーザー単位の識別ヘッダー

provider: anthropic のアップストリームの base_url を、Anthropic API ではなく自分が運用するプロキシに向けることができます。そのプロキシに、どの開発者がリクエストを送信したかを伝えるには、そのアップストリームで forward_user_identity: true を設定します。これにより、プロキシは開発者ごとに利用量を割り当てられます。ゲートウェイに Claude Code v2.1.233 以降が必要です。

例えば、upstream-gateway.internal.example.com にあるプロキシの場合は次のようになります。

upstreams:
  - provider: anthropic
    base_url: https://upstream-gateway.internal.example.com
    auth:
      api_key: ${PROXY_KEY}
    forward_user_identity: true        # default false

ゲートウェイは、そのアップストリームへ転送するすべてのリクエストに、次のヘッダーを追加します。

ヘッダー 値
x-litellm-end-user-id 開発者のメールアドレス（IdP が提供した場合）。
x-claude-gateway-user-id トークンの sub クレームに含まれる、開発者の IdP subject。
x-claude-gateway-user-email 開発者のメールアドレス（IdP が提供した場合）。

IdP トークンにメールアドレスが含まれていない場合、ゲートウェイは x-claude-gateway-user-id のみを送信し、メールアドレスに関する 2 つのヘッダーは省略します。IdP がメールアドレスを別のクレームに格納している場合は、oidc.email_claim をそのクレームに設定してください。

開発者のメールアドレスを伴うリクエストに対して、プロキシが 429 を返した場合、ゲートウェイはそのレスポンスをそのまま開発者に返し、次のアップストリームへのフェイルオーバーは行いません。これにより、プロキシのユーザー単位の予算やレート制限が維持されます。プロキシのそれ以外のレスポンスは、通常のフェイルオーバーのルールに従います。開発者の IdP トークンにメールアドレスが含まれていない場合、ゲートウェイはメールアドレスのヘッダーなしでそのリクエストを転送するため、そのリクエストに対する 429 はアップストリームの容量超過として扱われ、フェイルオーバーします。ゲートウェイサーバー側で v2.1.267 より前では、すべての 429 がフェイルオーバーの対象でした。

forward_user_identity は、base_url が自分の運用するプロキシであるアップストリームにのみ設定してください。ゲートウェイは、その base_url が指すサーバーに、開発者のメールアドレスを送信します。既定である base_url が Anthropic API の場合、ゲートウェイは起動を拒否します。

取得日 · 2026-09-23

変更の詳細