ゲートウェイの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
ゲートウェイは、そのアップストリームへ転送するすべてのリクエストに、次のヘッダーを追加します。
| Header | Value |
|---|---|
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 をそのクレームに設定してください。
プロキシには、Claude Code が送信する x-claude-code-* ヘッダー(x-claude-code-session-id など)は渡されません。ゲートウェイはこれらをどのアップストリームにも渡さないため、開発者ごとにリクエストをグループ化するには、上の表のヘッダーを使用してください。
開発者のメールアドレスを伴うリクエストに対して、プロキシが 429 を返した場合、ゲートウェイはそのレスポンスをそのまま開発者に返し、次のアップストリームへのフェイルオーバーは行いません。これにより、プロキシのユーザー単位の予算やレート制限が維持されます。プロキシのそれ以外のレスポンスは、通常のフェイルオーバーのルールに従います。開発者の IdP トークンにメールアドレスが含まれていない場合、ゲートウェイはメールアドレスのヘッダーなしでそのリクエストを転送するため、そのリクエストに対する 429 はアップストリームの容量超過として扱われ、フェイルオーバーします。ゲートウェイサーバー側で v2.1.267 より前では、すべての 429 がフェイルオーバーの対象でした。
forward_user_identity は、base_url が自分の運用するプロキシであるアップストリームにのみ設定してください。ゲートウェイは、その base_url が指すサーバーに、開発者のメールアドレスを送信します。既定である base_url が Anthropic API の場合、ゲートウェイは起動を拒否します。
[!NOTE]
Amazon Bedrock アップストリームで
forward_user_identityを設定すると、ゲートウェイは起動時にUnrecognized key(s) in object: 'forward_user_identity'というエラーで終了します。プロキシが Bedrock の手前にある場合は、代わりにprovider: anthropicのアップストリームとして登録してください。ゲートウェイはそのアップストリームに Anthropic の Messages 形式でリクエストを送るため、プロキシ側でBedrock 向けにリクエストを変換する必要があります。代わりに各開発者を AWS に伝える方法については、開発者ごとの AWS コスト配分を参照してください。
取得日 · 2026-11-20