Migrating to Claude Sonnet 5.5: Every Breaking Change

Claude Sonnet 5.5, released on September 28, 2026, costs the same as Sonnet 5, so many teams will try it by changing one line: the model ID. On a typical Sonnet 5 integration that change alone can return errors. Anthropic’s migration guide lists five request settings that Sonnet 5.5 rejects with a 400 error, a new way to turn thinking off, and several changes that fail silently.

This guide collects them in the order you will meet them, with Anthropic’s exact error text, and then groups the work by the model you are moving from. Everything here comes from Anthropic’s migration guide and What’s new page as published on launch day, plus the preserved-thinking documentation linked below; the OpenRouter alias check is our own observation.

Anthropic names five request settings that Sonnet 5.5 refuses. Each one returns an invalid_request_error with HTTP status 400, so the request fails before the model runs. The error strings below are Anthropic’s; an ellipsis marks where we shortened one.

Which of the five you hit depends on your starting model. Sonnet 5 already rejected thinking budgets, sampling parameters and prefill, so a Sonnet 5 integration meets only the first two rows. Code written for Sonnet 4.5 or Haiku 4.5 can meet all five.

For forced tool choice, Anthropic’s replacement is tool_choice: {"type": "auto"} with the tool marked strict: true, so that any call the model makes matches the schema. Because the model may now answer without calling the tool, the prompt has to say when the tool applies. A request can carry at most 20 strict tools, and strict mode needs additionalProperties: false on every object. On Amazon Bedrock, structured outputs and strict tools are not available for Sonnet 5.5, so send auto alone and validate the tool input in your own code.

On Sonnet 5.5 a request with no thinking field runs with adaptive thinking, as it did on Sonnet 5. Teams that switched thinking off on Sonnet 5 to save tokens or latency need the new setting, thinking: {"type": "between_tools"}. Anthropic describes it as the lowest thinking setting: the model does no up-front thinking, and short progress notes between tool calls still come back as thinking blocks with their summary text. Without tools, the response is text only.

One detail matters for teams that ran Sonnet 5 with thinking off at a high effort level. Anthropic’s own before-and-after example moves a Sonnet 5 request from disabled at xhigh to between_tools at high, because xhigh is no longer allowed with thinking off. If a workload genuinely needs xhigh or max, it has to accept adaptive thinking. With Anthropic’s server-side fallback turned on, a between_tools request that falls back to Sonnet 5 runs there with thinking disabled.

The fix for the second rule is to keep conversations append-only. Change instructions or tools with mid-conversation system messages instead of editing earlier turns. With adaptive thinking, the beta header thinking-binding-controls-2026-08-01 plus thinking.block_binding.prefix_mismatch_behavior: "drop_block" lets a request drop failing blocks instead of erroring, and reports each drop in an input_transformations array. With between_tools, sending block_binding returns a 400, so keep the history append-only. Anthropic’s preserved-thinking documentation warns that dropping hides the error without fixing the edit, and that the model may spend extra tokens re-creating lost reasoning.

The account rule is new with Sonnet 5.5 and is part of Anthropic’s defence against distillation. Most developers will not notice it. The case that does notice is a conversation that moves between accounts, including switching accounts mid-session in Claude Code: the session continues, but without its earlier reasoning.

Computer use needs the toolset. On the Claude API and Google Cloud, Sonnet 5.5 accepts computer use only through computer_toolset_20260801. The older computer_20251124 tool, sent by Sonnet 5 and 4.6 integrations, returns a 400 there but still works on Amazon Bedrock. The even older computer_20250124 is rejected on every platform. Remove the fine-grained-tool-streaming-2025-05-14 beta header when you move, because it errors alongside a toolset entry; set eager_input_streaming: true on each tool instead.

The advisor tool accepts fewer advisors. A Sonnet 5.5 executor needs Opus 5, Opus 5.5, Sonnet 5.5, Fable 5 or 5.1, or Mythos 5 or 5.1 as its advisor. Opus 4.8, 4.7 and 4.6, Sonnet 5 and Sonnet 4.6 return a 400, and the advice now comes back encrypted.

More refusal categories. Sonnet 5.5 can decline under five named categories: cyber, bio, frontier_llm, reasoning_extraction and general_harms. A decline arrives as stop_reason: "refusal", not as an HTTP error, so code that only checks the status code will miss it. The server-side fallback beta (fallbacks: "default", Claude API only) retries cyber and frontier-LLM declines on Sonnet 5 and does not retry the other three.

The guide’s checklist works cumulatively: start at the top and stop at your model. The table condenses it. Anthropic also ships a Claude Code command, /claude-api migrate, that applies the model-ID swap and the parameter changes across a codebase and then lists what to verify by hand. Teams on Claude Managed Agents only need to change the model name.

Two cost notes sit inside that table. Sonnet 5.5 uses Sonnet 5’s tokenizer, which produces about 30% more tokens than Sonnet 4.6, 4.5 or Haiku 4.5 for the same text, so a team moving from those models should recount tokens rather than compare old and new bills per token. Images are also processed at a higher resolution, and Anthropic’s example of a 2000 by 1500 pixel image costs about 2.5 times the tokens it did on Sonnet 4.6.

• Progress notes go quiet. Notes longer than a sentence or two that the model writes between tool calls now come back as thinking blocks, empty at the default display setting. An interface that streams them to users shows nothing. Set display to "summarized", or to "updates" with a beta header, or use between_tools.
• Code that reads the first block breaks. A response can start with a thinking block, so read blocks by type, and pass thinking blocks back unchanged in tool loops.
• Effort levels are recalibrated. The default on the API is high, and a named level does not produce the same amount of thinking as on Sonnet 5. Anthropic suggests medium for well-specified agentic coding and medium or low for chat. Our effort ladder reference compares the levels across vendors.
• Aliases can move for you. At our check at 21:28 UTC on September 28, OpenRouter’s ~anthropic/claude-sonnet-latest pointed at Sonnet 5.5; on September 25 it pointed at Sonnet 5. Code calling that alias changed model with no deploy. The alias and retirement ledger tracks these moves.

One change helps: the minimum prompt that can be cached drops to 512 tokens from 1,024 on Sonnet 5, so shorter prompts can now be cached. Pricing, benchmarks and safeguards are covered in our Sonnet 5.5 launch post.