### Plan Claude Code version upgrades
The whole hunk
from line 253, old and new numbered
/
lines
from line 253
253253
254254After rollout, three kinds of change reach the gateway over time. Each has a symptom to watch for and an action to take.
255255
256| Change | Symptom when the gateway hasn't kept up | Action |
257| :--------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
258| New Claude Code releases add `anthropic-beta` values and request body fields | Developers report `400` errors naming a new field after they update Claude Code; see [feature pass-through](/docs/en/llm-gateway-protocol#feature-pass-through) | Forward `anthropic-*` headers and request bodies verbatim rather than allowlisting; test new Claude Code releases against the gateway before they reach developers |
259| New Claude models become available | Developers selecting a new model name get `404`; the `/model` picker doesn't list it | Add the model name to the gateway's routing configuration, then re-run the [routing check](#confirm-the-gateway-routes-your-models). If you distribute `ANTHROPIC_MODEL` or the default-model variables, update the managed settings |
260| Credentials expire or need rotation | All developer requests start failing with `401` from the upstream | Rotate the gateway's provider credential on its own schedule; developer keys rotate at the gateway, and an [`apiKeyHelper`](/docs/en/llm-gateway-connect#rotate-credentials-with-apikeyhelper) handles per-developer rotation without redistributing settings |
256| Change | Symptom when the gateway hasn't kept up | Action |
257| :--------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
258| New Claude Code releases add `anthropic-beta` values and request body fields | Developers report `400` errors naming a new field after they update Claude Code; see [feature pass-through](/docs/en/llm-gateway-protocol#feature-pass-through) | Forward `anthropic-*` headers and request bodies verbatim rather than allowlisting; test new Claude Code releases against the gateway before they reach developers, checking the areas in [Plan Claude Code version upgrades](#plan-claude-code-version-upgrades) |
259| New Claude models become available | Developers selecting a new model name get `404`; the `/model` picker doesn't list it | Add the model name to the gateway's routing configuration, then re-run the [routing check](#confirm-the-gateway-routes-your-models). If you distribute `ANTHROPIC_MODEL` or the default-model variables, update the managed settings |
260| Credentials expire or need rotation | All developer requests start failing with `401` from the upstream | Rotate the gateway's provider credential on its own schedule; developer keys rotate at the gateway, and an [`apiKeyHelper`](/docs/en/llm-gateway-connect#rotate-credentials-with-apikeyhelper) handles per-developer rotation without redistributing settings |
261261
262262When sizing per-key rate limits, account for the client [retrying transient failures](/docs/en/errors#automatic-retries), including `429` responses, up to 10 times with backoff, honoring `Retry-After`. Keep the [compatibility guide](/docs/en/llm-gateway-protocol) as the reference for what each Claude Code release sends.
263
264### Plan Claude Code version upgrades
265
266Some Claude Code behavior is built into the installed version rather than set at your gateway, so moving developers to a new release can change behavior across your deployment even when the gateway configuration hasn't changed. To control when that happens, pin developers to a tested version with [`requiredMaximumVersion`](/docs/en/settings-reference#requiredmaximumversion), or with [`DISABLE_UPDATES`](/docs/en/setup#disable-auto-updates) if you distribute Claude Code through your own channel. Before you raise the pin, read the new release's [changelog](/docs/en/changelog) entry and [test it against the gateway](#test-claude-code-against-the-gateway).
267
268When you test a release, new headers or request fields that the gateway rejects appear as the `400` errors described in [Maintain the gateway](#maintain-the-gateway). The table below covers version-dependent changes that don't produce an error, with the setting that keeps each one constant across upgrades.
269
270| Area | What can change when developers upgrade | Setting that keeps it constant |
271| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
272| Feature-flag defaults | Sessions that [don't fetch feature flags from Anthropic](/docs/en/env-vars#features-that-need-feature-flag-fetching), such as sessions on a cloud provider or with telemetry turned off, use the flag defaults built into the installed version. When a release changes one of those defaults, the behavior changes for those developers as soon as they upgrade | The version pin itself, `requiredMaximumVersion` or `DISABLE_UPDATES` |
273| Model capability assumptions | A model ID that the installed version doesn't recognize, such as the gateway alias `prod-opus`, runs on default assumptions for [adaptive reasoning](/docs/en/model-config#adaptive-reasoning-and-fixed-thinking-budgets), the effort parameter, and the [context window](/docs/en/model-config#correct-the-window-for-a-gateway-or-custom-model-id) until a later version recognizes the ID or you map it | Route Anthropic model IDs at the gateway, or add a [`modelOverrides`](/docs/en/model-config#override-model-ids-per-version) entry that maps the Anthropic model ID to your alias. On a cloud provider connection, you can instead [declare a pinned model's capabilities](/docs/en/model-config#customize-pinned-model-display-and-capabilities) |
274| Default model and aliases | The model that new sessions start on by default, and the models that aliases such as `opus` and `sonnet` resolve to, are [built into each version](/docs/en/model-config#pin-models-for-third-party-deployments) and can change when developers upgrade | [`ANTHROPIC_DEFAULT_MODEL`](/docs/en/model-config#set-a-default-model-for-new-sessions) for the model new sessions start on, and the [`ANTHROPIC_DEFAULT_*_MODEL` variables](/docs/en/model-config#environment-variables), such as `ANTHROPIC_DEFAULT_OPUS_MODEL`, for what each alias resolves to. `ANTHROPIC_DEFAULT_MODEL` requires Claude Code v2.1.236 or later |
263275
264276## Related resources
265277