Return 429 without upstream failover

Per-user identity headers for a proxy you run

You can point a provider: anthropic upstream's base_url at a proxy you run instead of at the Anthropic API. To tell that proxy which developer sent each request, set forward_user_identity: true on that upstream. The proxy can then attribute spend per developer. Requires a gateway running Claude Code v2.1.233 or later.

For example, for a proxy at 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

The gateway adds these headers to every request it forwards to that upstream.

Header	Value
x-litellm-end-user-id	The developer's email, when the IdP supplied one.
x-claude-gateway-user-id	The developer's IdP subject, from the token's sub claim.
x-claude-gateway-user-email	The developer's email, when the IdP supplied one.

When the IdP token carries no email, the gateway sends only x-claude-gateway-user-id and omits the two email headers. If your IdP puts the email in a different claim, set oidc.email_claim to that claim.

When your proxy answers 429 to a request that carried the developer's email, the gateway returns that response to the developer as-is instead of failing over to the next upstream, so your proxy's per-user budget or rate limit holds. The proxy's other responses follow the ordinary failover rules. If a developer's IdP token carries no email, the gateway forwards their requests without the email headers, so a 429 to one of those requests counts as upstream capacity and fails over. Before v2.1.267 on the gateway server, every 429 failed over.

Set forward_user_identity only on an upstream whose base_url is a proxy you operate. The gateway sends developer emails to whatever server that base_url names. If the base_url is the Anthropic API, which is the default, the gateway refuses to start.