[DOCS] Fallback model docs omit `fallbackModel` ordered-list configuration and retry semantics

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/settings

Section/Topic

fallbackModel settings support, ordered fallback behavior, and retry semantics

Current Documentation

The settings reference has no fallbackModel entry in its available settings table.

The model configuration page explains how to choose a primary model, but it does not describe any persistent fallback-model setting or ordered fallback list behavior.

The Agent SDK TypeScript reference lists:

fallbackModel | string | undefined | Model to use if primary fails

The environment variables page separately says:

FALLBACK_FOR_ALL_PRIMARY_MODELS ... trigger fallback to --fallback-model after repeated overload errors on any primary model. By default, only Opus models trigger the fallback

What's Wrong or Missing?

Claude Code v2.1.166 added or clarified fallback-model behavior that is still not documented in the user-facing Claude Code docs:

• fallbackModel can configure up to three fallback models tried in order.
• Claude Code retries a turn once on the fallback model when the API rejects an unexpected non-retryable error.
• Auth, rate-limit, request-size, and transport errors still surface immediately.

There is already an open issue for the outdated --fallback-model interactive-session text. This issue is about the remaining undocumented behavior that is not covered by that contradiction:

• the existence of a persistent fallbackModel setting in Claude Code
• whether it is a single string or an ordered list of up to three models
• how its retry order works
• which error classes trigger fallback retries versus surfacing immediately
• how the setting relates to --fallback-model and FALLBACK_FOR_ALL_PRIMARY_MODELS

Today, the user-facing Claude Code docs leave fallback behavior fragmented across unrelated pages and partly visible only in SDK docs. That makes it hard for users to configure fallback intentionally or predict what Claude Code will do after overloads, unavailable models, or unexpected API failures.

Suggested Improvement

Add a fallbackModel entry to the settings reference and expand the model-configuration docs with a dedicated fallback section that covers:

• whether fallbackModel is configured as a string or array
• the maximum of three ordered fallback models
• when Claude Code falls back because the primary model is overloaded or unavailable
• the one-time retry on a fallback model for unexpected non-retryable API errors
• the errors that do not trigger fallback: auth, rate-limit, request-size, and transport failures
• how FALLBACK_FOR_ALL_PRIMARY_MODELS changes the trigger conditions
• how the persistent setting interacts with the CLI --fallback-model flag

Suggested documentation direction:

fallbackModel configures up to three fallback models in priority order. Claude Code uses them when the primary model is overloaded or unavailable, and can retry a turn once on a fallback model after certain unexpected API failures. Authentication, rate-limit, request-size, and transport errors are surfaced immediately instead of triggering fallback.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/settings | 166-223 | Available settings table does not include fallbackModel |
| https://code.claude.com/docs/en/model-config | 48-139 | Model selection docs do not explain persistent fallback model configuration |
| https://code.claude.com/docs/en/env-vars | 301 | FALLBACK_FOR_ALL_PRIMARY_MODELS refers to fallback behavior without a full fallback-model explanation |
| https://code.claude.com/docs/en/errors | 636 | Errors page mentions fallback in broad terms only |
| https://code.claude.com/docs/en/agent-view | 281-287 | Notes that --fallback-model carries into background sessions, but not how fallback selection works |
| https://code.claude.com/docs/en/agent-sdk/typescript | 420 | SDK reference exposes fallbackModel without equivalent Claude Code user docs |

Total scope: 6 pages affected.

Version reference: Claude Code v2.1.166 release notes state that fallbackModel configures up to three fallback models tried in order and that Claude Code retries a turn once on the fallback model for an unexpected non-retryable API error.