Migrating to Claude Sonnet 5.5? Five Changes That Break Working Code

If your code runs on Claude Sonnet 5, swapping the model ID to claude-sonnet-5-5 is not a safe one-line upgrade. According to Anthropic's migration guide, five changes can return a 400 error, and a sixth changes the shape of the response without failing any request.

The two most likely to hit a working app are thinking: {"type": "disabled"} and forced tool use. Both now return an error on Sonnet 5.5.

This article walks through what changed, what to send instead, and how to test the move before it reaches users. Every behavior below comes from Anthropic's documentation as of October 2, 2026. Check the current docs before you ship, because API details move quickly.

Why is this migration different from a normal model swap?

Most model upgrades change quality, speed, and price. Sonnet 5.5 also changes request validation.

Anthropic's September 28 announcement says Sonnet 5.5 is priced the same as Sonnet 5, at $2 per million input tokens and $10 per million output tokens, and that Anthropic measured up to 30% lower cost per task in its own testing. I covered that cost claim and how to test it in the Sonnet 5.5 cost-per-task article.

Price parity is the reason teams will want to move quickly. The validation changes are the reason not to do it blindly.

The migration guide says every starting model needs the Sonnet 5 changes, then lists extra work for teams coming from Sonnet 4.6 or earlier. The what's new page summarizes the same five breaking changes.

What happens to thinking: {"type": "disabled"}?

On Sonnet 5.5 it returns a 400 invalid_request_error.

Sonnet 5.5 runs adaptive thinking by default, even when a request has no thinking field. That differs from Sonnet 4.6 and earlier, where a request without the field ran without thinking.

To keep the old no-upfront-thinking behavior, Anthropic says to send:

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

A few rules from the guide matter in practice:

• between_tools is the lowest thinking setting on Sonnet 5.5. It needs no beta header.
• It works at low, medium, and high effort. At xhigh or max it returns a 400 error.
• It takes no other thinking field. Sending display, budget_tokens, or block_binding with it also returns a 400 error.
• Effort cannot change mid-conversation with it. A per-message output_config.effort that differs from the level in effect returns a 400 error.

The last two are easy to miss. A shared request builder that always adds a display value, or a router that picks effort per turn, can break only on the between_tools path.

One more detail: the guide says a between_tools request that falls back to Sonnet 5 through server-side fallback runs there with thinking: {"type": "disabled"}. That is intended behavior, not a mismatch to debug.

If your SDK predates the new value, the guide notes that Python and TypeScript examples can fail type checking until you update the SDK. You can also pass the value as raw JSON.

What replaces forced tool use?

Sonnet 5.5 rejects a tool_choice of type any or tool with a 400 error, including on the token counting endpoint.

The documented replacement is tool_choice: {"type": "auto"} plus strict: true on the tool, so the input matches your schema. Strict tool use supports a subset of JSON Schema and needs additionalProperties: false on every object.

There is a behavioral catch, and the guide states it directly: with auto, the model can answer without calling the tool. Your prompt now has to say when the tool should be used.

Amazon Bedrock is different. The guide says structured outputs, which include strict tool use, are not available for Sonnet 5.5 there. On Bedrock it recommends auto without strict, a prompt that says when to call the tool, and validation of the tool input in your own code.

This is the change I would test first. Forced tool use is a common way to get reliable structured extraction. Moving to auto turns a guarantee into a probability, even with a strict schema. Add a check for the case where no tool call comes back, and decide what your app does then: retry, ask again with a firmer instruction, or fail visibly.

Why can thinking blocks break a tool loop?

Two separate rules apply here.

First, thinking blocks are tied to the model. The guide says Sonnet 5.5 reads blocks from Sonnet 5, Opus 4.8, Haiku 4.5, and earlier models. It does not read blocks from Opus 5, Opus 5.5, or any Fable or Mythos model. The API drops blocks the model cannot read, still returns 200, and does not bill dropped blocks. If you switch models mid-conversation, reasoning continuity can quietly change without an error.

Second, 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, the API enforces this by default on the Claude API, Amazon Bedrock, and Google Cloud. A request that replays a block after earlier history was edited returns a 400 error.

The practical rule is to keep conversations append-only. If your app trims, rewrites, or summarizes earlier turns while preserving old thinking blocks, test that path. The guide says to change instructions or tools with mid-conversation system messages instead.

The guide also says to pass thinking blocks back unchanged in tool-use loops, including empty ones. And read response content by block type, because a response can now begin with a thinking block. Code that reads content[0].text breaks.

What about computer use and the advisor tool?

These two changes affect fewer teams, but both fail loudly.

For computer use on the Claude API and Google Cloud, Sonnet 5.5 supports only the computer_toolset_20260801 toolset there. computer_20251124 returns a 400 error. computer_20250124 is not accepted on any platform. On Amazon Bedrock, the guide says to send computer_20251124.

If you send the fine-grained-tool-streaming-2025-05-14 beta header, remove it when moving to the toolset. The guide says it returns a 400 error alongside a toolset entry, and that you should set eager_input_streaming: true on each tool that needs it.

For the advisor tool, a Sonnet 5.5 executor needs an advisor from this list: Opus 5, Opus 5.5, Sonnet 5.5, Fable 5, Fable 5.1, Mythos 5, or Mythos 5.1. Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 5, and Sonnet 4.6 advisors return a 400 error. The advice comes back encrypted, so its text is not readable in the response.

What changes without throwing an error?

Text between tool calls.

On Sonnet 5.5, notes longer than a sentence or two that the model writes between tool calls come back as progress-update thinking blocks. They are empty at the default display value. Shorter remarks stay as text.

The guide says no request fails. But an interface that shows those notes to users goes quiet during tool calls.

If your UI streams "searching the database" style updates, this is the change that will look like a frontend bug. Per the guide, with adaptive thinking you can set display to "updates" (a beta feature with its own header) to get the updates alone, or "summarized" to get them mixed with reasoning. With between_tools, the text comes back without display.

Also revisit max_tokens. It covers thinking plus text, and the guide says thinking tokens are billed as output tokens.

Which safety and fallback behavior should you plan for?

Sonnet 5.5 can decline in more categories than Sonnet 5. A decline returns stop_reason: "refusal", and stop_details can name a category: cyber, bio, frontier_llm, reasoning_extraction, or general_harms. The guide notes benign work can also trigger general_harms.

Anthropic's announcement says Sonnet 5.5 is the first Sonnet model to launch with cyber safeguards and fallbacks like those used for its most capable models, and that the safeguards target a narrow set of high-risk requests. Routine software development and most life sciences work are described as unaffected.

Server-side fallback, a beta feature on the Claude API only, retries cyber and frontier_llm declines on Sonnet 5. It does not retry bio, reasoning_extraction, or general_harms declines.

For security tooling, the guide says to apply to Anthropic's Cyber Verification Program. If your product does vulnerability work, treat this as a launch task, not a post-launch fix.

How should you test the migration?

This is a hypothetical example, not a report from a real deployment. Suppose an internal support assistant extracts a ticket category by forcing a tool call, hides model reasoning, and streams short progress text to the screen.

Before switching traffic, I would run these checks against a staging key:

1. Replay your request builders. Send one request for every code path with the new model ID. Any 400 error from disabled, forced tool_choice, or an old computer-use tool shows up immediately.

2. Search for hard-coded content indexes. Look for content[0] and similar assumptions. Parse by block type.

3. Test tool-skipping. After moving to auto, send inputs that should and should not call the tool. Count how often the tool call is missing, and handle it.

4. Test a long conversation. Edit or trim earlier history in staging, then continue the thread. This catches signed-block failures.

5. Watch the UI. Run a tool-heavy task and check whether progress text still appears.

6. Re-sweep effort. The guide says levels are recalibrated, so the same level does not produce the same amount of thinking as on Sonnet 5. Anthropic suggests starting at high unless the workload is agentic or latency-sensitive, and at medium for well-specified agentic work.

7. Re-baseline cost. Compare cost per completed task, not only price per token.

For Sonnet 4.6 and earlier, add the extra items from the guide: expect thinking on requests with no thinking field, replace thinking budgets with an effort level, and remove non-default temperature, top_p, and top_k values.

Anthropic also says the /claude-api migrate skill in Claude Code can apply the model ID swap and breaking parameter changes, then produce a checklist to verify manually. I would still read the diff it produces. It is a starting point, and the verification list is the part that protects you.

What I would do first

Pin the old model in production, migrate a staging branch, and fix errors in this order: thinking, tool_choice, content parsing, then tool-loop history. Those are the failures that stop requests. Progress text, effort, and cost come next because they change quality and user experience instead.

The model is cheaper per task in Anthropic's testing. That says nothing about whether your application's wrapper code is ready for it.

FAQ

Can I just change the model ID to claude-sonnet-5-5?

Only if your requests avoid the changes in Anthropic's migration guide. The guide lists model ID changes plus several breaking parameter changes. Test every request path before moving production traffic.

What replaces thinking: {"type": "disabled"} on Sonnet 5.5?

Anthropic documents thinking: {"type": "between_tools"}. It works at low, medium, and high effort and returns a 400 error at xhigh or max. Sonnet 5 and earlier models still use the older way of turning thinking off.

Why does my forced tool call return a 400 error?

Sonnet 5.5 does not support tool_choice types any or tool. The documented replacement is auto with a strict tool, plus a prompt that says when to use the tool. On Amazon Bedrock, use auto without strict and validate the input yourself.

Why did my UI stop showing progress text between tool calls?

According to the migration guide, longer notes between tool calls now come back as thinking blocks, which are empty at the default display value. Set a supported display value with adaptive thinking, or use between_tools, where the text comes back without display.

Does Sonnet 5.5 cost less than Sonnet 5?

Anthropic lists the same token prices and says it measured up to 30% lower cost per task in its own testing. Your result depends on your prompts, effort level, thinking use, and failure rate. Measure cost per completed task.

Can I switch between Claude models inside one conversation?

Possibly, but thinking blocks are tied to the model. The guide says Sonnet 5.5 cannot read blocks from Opus 5, Opus 5.5, or Fable and Mythos models. The API drops them and still returns 200, so test quality when you switch.

Is the Claude Code migration skill enough?

It can do the mechanical edits and produce a checklist, according to Anthropic. It does not replace tests against your own prompts, tools, UI, and conversation history.