Skip to main content

Models

A model is the Claude version that answers you. Effort is how hard the model thinks before it answers. An API call is one request to the model server. This page explains how Claude Code chooses each of these and what happens when a call fails. The full list of models, aliases, and providers is on Models and Providers.

Choosing the Model​

Sources: Model Configuration and Hooks Reference.

Other pages list the items that set the model. They are flags, environment variables, settings, aliases such as default, opusplan, and best, the [1m] suffix, and the switch hooks. See Choose a Model and Aliases.

A switch of the model is a cache miss. See Request and Cache.

Effort​

The effort levels are low, medium, high, xhigh, and max. A level that the model does not accept runs as the highest accepted level below it. Source: Model Configuration.

The flags, variables, settings, request field, and default level for each model are in Effort. The cache warning, the prompt note, and the spinner text for an effort change are in the same section.

Thinking​

Sources: Model Configuration and Environment Variables.

The thinking flags, variables, and settings are in Thinking.

MAX_THINKING_TOKENS cannot turn thinking off on Opus 5.5, Sonnet 5.5, Haiku 5.5, and the Fable models. CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING has no effect on newer models.

Capabilities​

The model catalog gives each model a list of capability flags. The code tests a flag to enable a feature for that model. The flag list, with what each flag does and how many models have it, is in Capabilities. The flags effort, max_effort, xhigh_effort, and adaptive_thinking say which effort levels and which thinking mode a model accepts. The betas per-turn-control-2026-07-01 and timing-2026-09-09 match the flags per_turn_effort and per_turn_timing.

Fallback​

  • A fallback chain (--fallback-model, fallbackModel) holds at most three models. It covers overload and server errors, and not auth, billing, rate-limit, request-size, or transport errors. The switch lasts for the current turn. The next turn tries the main model first. Source: Model Configuration: Fallback Model Chains.
  • Content-based fallback applies to the Fable models, Opus 5.5, Sonnet 5.5, and Opus 5. A request that is flagged as biology or cybersecurity runs again on the fallback model of that category. The session then stays on that model. Source: Model Configuration: Automatic Model Fallback.
  • CLAUDE_CODE_NO_MODEL_FALLBACK forbids the substitution of a model (
    Undocumented: Only the program shows this item. It can change without notice.
    , a message in the program names it).

Retries and Timeouts​

Sources: Error Reference: Automatic Retries and Environment Variables.

The variables, with their defaults, are in Fallback and Retries.

Since 2.1.311, Claude Code does not retry a 429 or 529 that the API marked with x-should-retry: false, and that includes unattended mode (CLAUDE_CODE_RETRY_WATCHDOG). Before, such a request could hold a turn for minutes, or for good in that mode. Source: the Claude Code changelog, and the program (chunk-2ht8z368.js:131464; the old rule is chunk-31gxg38t.js:137298 in the 2.1.310 program).

When a request is too long for the context, Claude Code tries again with a smaller max_tokens. It compacts when that is not enough. Since 2.1.311, a session on a standard window (not 1M) that sends more than 200K tokens and gets the error "Usage credits required for 1M context" compacts the conversation and goes on, where it stopped before. Source: the Claude Code changelog, and the program (chunk-8qajn51r.js:6009 checks for that refusal on a model whose window is standard, then the code at chunk-8qajn51r.js:11603 to :11700 runs the reactive compaction). The loop also recovers from a stop at max_tokens and from a bad tool call. See The Agent Loop.

Example​

Run one hard task with a stronger model and more thinking. Make a script fail sooner by lowering the retry count.

claude --model opus --effort high
CLAUDE_CODE_MAX_RETRIES=3 claude -p "summarize this repo"