What breaks when I switch from Claude Sonnet 5 to Sonnet 5.5?

Five settings return a 400 error on Claude Sonnet 5.5 as of September 28, 2026: thinking type 'disabled' (use 'between_tools' at low, medium or high effort instead), tool_choice of type 'any' or 'tool' (use 'auto' plus strict tools), thinking budgets, non-default temperature/top_p/top_k, and assistant prefill. Computer use on the Claude API and Google Cloud must move to the computer_toolset_20260801 toolset; Amazon Bedrock keeps computer_20251124. The advisor tool only accepts Opus 5, Opus 5.5, Sonnet 5.5, Fable 5/5.1 or Mythos 5/5.1 as advisors. Longer notes between tool calls now arrive as thinking blocks, and refusals return stop_reason 'refusal' with a category.

How do I turn thinking off on Claude Sonnet 5.5?

You can't fully. Send thinking: {"type": "between_tools"}, the lowest setting: no up-front thinking, but progress updates between tool calls still come back as thinking blocks. It works at low, medium and high effort and returns a 400 at xhigh or max. It accepts no other fields (no display, budget_tokens or block_binding), and effort cannot change mid-conversation while it is in effect. For per-turn effort changes use adaptive thinking (omit the thinking field).

Why does replaying a conversation return a 400 on Sonnet 5.5?

Sonnet 5.5 signs each thinking block over the conversation that precedes it. For accounts created on or after August 31, 2026 00:00 UTC the API enforces this on the Claude API, Amazon Bedrock and Google Cloud: replaying a block after editing earlier history returns a 400. Keep conversations append-only and change instructions or tools with mid-conversation system messages. Thinking blocks also only work in the account (or a linked account) that produced them.

Is there an automated way to migrate to Claude Sonnet 5.5?

Yes. In Claude Code run /claude-api migrate this project to claude-sonnet-5-5. The bundled Claude API skill swaps model IDs, applies breaking parameter changes, replaces prefills and recalibrates effort across the code base, asks you to confirm the scope first, and produces a checklist of items to verify by hand. It also detects Amazon Bedrock and Claude Platform on AWS clients and adjusts model ID formats for them. Claude Managed Agents users only need to change the model name.

Quick Answer

How to Migrate to Claude Sonnet 5.5: Breaking Changes (2026)

Published: September 29, 2026

The short answer

Migrating to Claude Sonnet 5.5 is a model-ID swap plus a handful of breaking API changes that mostly concern thinking and tool control. Change the model ID to claude-sonnet-5-5 (no date suffix), read content blocks by type, replace thinking: disabled with between_tools, replace forced tool_choice with auto plus strict tools, keep conversations append-only, move computer use to the computer_toolset_20260801 toolset (Claude API and Google Cloud), handle the new refusal categories, and re-run your effort sweep because the levels are recalibrated. Prices are unchanged from Sonnet 5 ($2/$10 per MTok). The fastest path is the bundled Claude Code skill: /claude-api migrate this project to claude-sonnet-5-5.

Step 0: decide whether to migrate

Sonnet 5.5 (September 28, 2026) is a large upgrade over Sonnet 5 at the same price — 70.6% vs 10.3% on Terminal-Bench 4.0, 30%+ faster, up to 30% cheaper per task. Full numbers in what is Claude Sonnet 5.5. If you are on Opus because Sonnet 5 fell short, read Sonnet 5.5 vs Opus 5.5 first. Coming from Haiku 4.5, budget for the higher per-token price ($2/$10 vs $1/$5) and re-check prompts that were too short to cache.

Step 1: the minimal working request

This request runs on Sonnet 5.5 as written. It leaves out the five settings that now return a 400: thinking budgets, sampling parameters, assistant prefill, forced tool choice and thinking: disabled.

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "..."}],
    output_config={"effort": "medium"},
)
for block in response.content:
    if block.type == "text":
        print(block.text)

Read blocks by type: a response can begin with a thinking block, so content[0].text breaks. Pass thinking blocks back unchanged in tool loops, including empty ones. Remember max_tokens covers thinking plus text, and thinking tokens bill as output.

Step 2: thinking is on by default — handle it

A request with no thinking field runs with adaptive thinking on Sonnet 5.5 (same as Sonnet 5; on Sonnet 4.6 and earlier it ran without thinking). Accepted thinking.type values are adaptive and between_tools; disabled and enabled are rejected. Thinking text is omitted by default (blocks arrive with an empty thinking field and a signature); set display: "summarized" to get readable summaries.

To run without up-front thinking:

"thinking": {"type": "between_tools"},
"output_config": {"effort": "high"}

between_tools is accepted at low, medium and high; at xhigh or max it returns a 400 — use adaptive thinking for those. It takes no other field, and a per-message output_config.effort that differs from the level in effect returns a 400, so per-turn effort changes need adaptive thinking. Without tools, the response is text only; with tools, progress updates between calls still arrive as thinking blocks with summary text.

Step 3: replace forced tool use

tool_choice of type any or tool returns a 400 on Sonnet 5.5, including on the token-counting endpoint. Send tool_choice: {"type": "auto"} and mark the tool strict: true so its input matches the schema (strict tools need additionalProperties: false on every object and support a subset of JSON Schema). Because the model can now answer without calling the tool, say in the prompt when to use it. On Amazon Bedrock use auto alone.

Step 4: keep conversations append-only

Each Sonnet 5.5 thinking block is signed over the conversation before it. For accounts created on or after August 31, 2026 00:00 UTC, replaying a block after an edit to earlier history returns a 400 on the Claude API, Amazon Bedrock and Google Cloud. Change instructions or tools with mid-conversation system messages instead of rewriting history. Thinking blocks are also account-bound: they work only in the account that produced them or a linked one, which affects anyone switching accounts mid-session in Claude Code.

Cross-model note: Sonnet 5.5 reads thinking blocks from Sonnet 5, Opus 4.8, Haiku 4.5 and earlier, but not from Opus 5, Opus 5.5, Fable or Mythos. The API drops unreadable blocks silently (200 response, not billed).

Step 5: tools that changed

Computer use. On the Claude API and Google Cloud, Sonnet 5.5 supports computer use only through computer_toolset_20260801; computer_20251124 returns a 400 there. On Amazon Bedrock send computer_20251124. computer_20250124 is rejected everywhere. Code already on the toolset needs no change.
Advisor tool. A Sonnet 5.5 executor needs one of: Opus 5, Opus 5.5, Sonnet 5.5, Fable 5, Fable 5.1, Mythos 5, Mythos 5.1. Opus 4.8 and earlier are no longer accepted, and advice comes back encrypted.
Text between tool calls. Notes longer than a sentence or two now arrive as progress-update thinking blocks (empty at default display); short remarks stay text. If your UI showed inter-tool commentary, read it from thinking blocks.

Step 6: handle refusals and configure fallback

Sonnet 5.5 declines in more categories than Sonnet 5. A decline returns stop_reason: "refusal" and stop_details names one of cyber, bio, frontier_llm, reasoning_extraction or general_harms (benign work can trip the last one). Server-side fallback (fallbacks: "default", beta, Claude API only) retries cyber and frontier_llm declines on Sonnet 5; it does not retry the other three. Real-time cyber safeguards are new for code coming from Sonnet 4.6, 4.5 or Haiku 4.5; legitimate security teams should apply to the Cyber Verification Program.

Step 7: re-run your effort sweep and re-baseline cost

Sonnet 5.5 has five effort levels — low, medium, high, xhigh, max — and they are recalibrated, so a level does not produce the same amount of thinking as on Sonnet 5. The Claude API defaults to high; Claude Code and the apps default to medium. Anthropic’s guidance: start at high unless the workload is agentic or latency-sensitive; for agentic coding start at medium and move to high for harder tasks; for chat start at medium or low. Watch max on coding: Anthropic’s own FrontierCode score at max (46.2%) is below xhigh (52.1%) because the model starts running multi-agent code review that overruns scope.

Also note the minimum cacheable prompt drops to 512 tokens (from 1,024), which lets shorter system prompts cache. Re-baseline cost per task, not per token — see how to maximize prompt-cache hit rate.

Extra steps if you are coming from older models

Sonnet 4.6 or earlier: expect thinking on requests with no thinking field; replace thinking budgets with an effort level; remove non-default temperature, top_p, top_k; recount tokens and re-budget image tokens.
Sonnet 4.5 or earlier: replace assistant prefills; parse tool input with a standard JSON parser; on Bedrock move computer_20250124 → computer_20251124; set output_config.effort explicitly; drop context-window and interleaved-thinking-2025-05-14 beta headers; replace fine-grained-tool-streaming-2025-05-14 with eager_input_streaming; move output_format → output_config.format.
Sonnet 4 or earlier: update tool versions to text_editor_20250728 and code_execution_20260521; handle refusal and model_context_window_exceeded stop reasons; remove token-efficient-tools-2025-02-19 and output-128k-2025-02-19.
Haiku 4.5: replace claude-haiku-4-5-20251001; re-baseline at the higher per-token price; revisit prompts that were too short to cache. If you only need the cheap tier, Haiku 5.5 is due “in the coming weeks” — consider waiting.

Verification checklist

A response with a leading thinking block parses correctly.
Tool loops pass empty thinking blocks back and never edit history.
No request sends tool_choice: any|tool, thinking: disabled, budget_tokens, or prefill.
Computer-use requests send the right tool version for the platform.
stop_reason == "refusal" is handled and, if applicable, fallbacks: "default" is set.
Cost per task on the new effort setting is within budget.

Last verified: September 29, 2026 against the Claude Platform migration guide.