← Back to blog
Tutorials#claude-api

Claude 5.5 Migration Checklist: Moving to Sonnet 5.5 or Opus 5.5 Without Breaking Your API Code

A step-by-step Claude 5.5 migration guide for developers: the request settings that now return a 400 on Sonnet 5.5 and Opus 5.5, how thinking blocks and edited history behave, how refusals are billed, and what to test before you switch traffic.

12 min readby the editors
Claude 5.5 Migration Checklist: Moving to Sonnet 5.5 or Opus 5.5 Without Breaking Your API Code cover illustration

Migrating to Claude 5.5 takes more than a new model ID. Claude Sonnet 5.5 and Claude Opus 5.5 are separate models with separate migration guides, and both reject request settings that older models accepted. Opus 5.5 returns a 400 if you try to disable thinking or set a thinking budget. Sonnet 5.5 rejects disabled thinking too, but offers a lower setting called between_tools. Both reject forced tool use, both can start a response with thinking blocks instead of text, and both tie those thinking blocks to the conversation that produced them. On newer accounts, editing earlier history can turn into a 400. This checklist walks through each change in the order you will hit it, labels which model it applies to, and ends with the tests to run before you route production traffic.

Before you start

System requirements

Target model IDs

claude-sonnet-5-5 and claude-opus-5-5

Same IDs on the Claude API, Claude Platform on AWS, Google Cloud, and Microsoft Foundry. Amazon Bedrock adds a prefix: anthropic.claude-sonnet-5-5 and anthropic.claude-opus-5-5.

Starting models covered

Sonnet 5, Sonnet 4.6 and older, Haiku 4.5, Opus 5, Opus 4.8 and older

Anthropic's Sonnet 5.5 guide covers Sonnet 5, 4.6, 4.5, 4, 3.7, and Haiku 4.5. The Opus 5.5 guide covers Opus 5, Opus 4.8 and earlier Opus models, and Sonnet 5.

What to have ready

A development API key and 20 to 50 real tasks

The task count is our recommendation, not an Anthropic requirement. You also want baseline numbers from the current model: success rate, tokens, latency, and cost per task.

Platforms

Windows, macOS and Linux

The API and SDKs are platform independent. The audit commands in step 2 are given for macOS and Linux (grep) and for Windows (PowerShell).

Facts checked

22 October 2026

Checked against Anthropic's migration guides, release notes, pricing, refusal, and preserved thinking pages, plus the GitHub Changelog. Pricing and enforcement rules can change, so re-check before you budget.

01

Which Claude 5.5 model are you migrating to?

Pick one target per route. Sonnet 5.5 and Opus 5.5 break in different ways, so follow one guide at a time.

Claude Sonnet 5.5 (launched September 28, 2026) is the Sonnet line's successor to Sonnet 5, at the same $2 / $10 per million input / output tokens. Anthropic also lists it as the migration path from Sonnet 4.6 and earlier, and from Haiku 4.5.

Claude Opus 5.5 (launched September 22, 2026) succeeds Opus 5 at a lower price: $4 / $20 per million tokens against $5 / $25. It is the path from Opus 4.8 and earlier, and from Sonnet 5 when you want an Opus-tier model.

Both have a 1M token context window and 128K max output. Coming from an older model, apply the intermediate guides first. A Sonnet 4.6 app, for example, picks up the Sonnet 5 changes (no budget_tokens, no custom temperature) before the Sonnet 5.5 ones.

If you mix models behind a router, migrate and test each route on its own. A setting that one model accepts can be a 400 on the other.

Which Claude 5.5 model is your target? Claude Sonnet 5, Sonnet 4.6 and older, and Claude Haiku 4.5 move to Claude Sonnet 5.5. Claude Opus 5 and Opus 4.8 and earlier move to Claude Opus 5.5, and Sonnet 5 can also step up to Opus 5.5. Sonnet 5.5, claude-sonnet-5-5: $2 / $10 per million tokens, cache reads $0.10, default effort high with recalibrated levels, thinking off through between_tools. Opus 5.5, claude-opus-5-5: $4 / $20 per million tokens, cache reads $0.20, default effort medium, thinking always on. Amazon Bedrock IDs add the anthropic. prefix.
Older models apply the intermediate guides first.Open full size →

Tip
SDK model constants such as CLAUDE_SONNET_5_5 can be missing from an older pinned SDK. The plain string claude-sonnet-5-5 works in every SDK.

02

Which settings in your code will now return a 400?

Search the codebase for the parameters that changed before you swap the model ID.

Run one of the commands below from the root of your repository. It lists model IDs, thinking settings, forced tool choices, old computer use tool versions, sampling parameters, and code that reads content[0] directly.

Review each match by hand. Most will be fine. The ones to fix are covered in the next steps: disabled thinking and thinking budgets (step 3), forced tool_choice (step 4), and position-based parsing (step 5).

Computer use: on the Claude API and Google Cloud, both models accept only the computer_toolset_20260801 toolset. The older computer_20251124 tool returns a 400 there, though Amazon Bedrock still accepts it. The toolset changes the agent loop as well as the tool entry, so give it its own test pass.

Sonnet 5.5 only: the advisor tool rejects Claude Opus 4.8, Opus 4.7, and Sonnet 5 as advisors.

From Sonnet 4.6, Sonnet 4.5, or Haiku 4.5: remove non-default temperature, top_p, and top_k values and any assistant prefill. Both return a 400 on the 5.5 models.

macOS / Linux
grep -rnE --exclude-dir={.git,node_modules,.venv} \
  "claude-(opus|sonnet|haiku)-|thinking|tool_choice|computer_202|temperature|top_p|top_k|content\[0\]" .
Windows (PowerShell)
Get-ChildItem -Recurse -File |
  Where-Object { $_.FullName -notmatch '\\(\.git|node_modules|\.venv)\\' } |
  Select-String -Pattern 'claude-(opus|sonnet|haiku)-|thinking|tool_choice|computer_202|temperature|top_p|top_k|content\[0\]'

Tip
Also search config files, environment variables, and infrastructure templates. Model IDs often live outside the application code.

03

How do you replace disabled thinking and thinking budgets?

On both models, effort is now the main control. The fix differs by model.

Opus 5.5: thinking is always on. thinking: {type: "disabled"} and {type: "enabled", budget_tokens: N} both return a 400 at every effort level. Remove the thinking field (or send {type: "adaptive"}) and set output_config.effort instead. Use low when time to first token matters.

Opus 5.5 also changed the default effort. It is now medium, where Opus 5 defaulted to high, so a request that omits effort runs one level lower than before. Set it explicitly.

Sonnet 5.5: {type: "disabled"} returns a 400 as well. Anthropic's first suggestion is adaptive thinking at low effort. If a route must stay thinking-off, send {type: "between_tools"}. It works only at effort high or below, takes no other field inside thinking, and does not allow per-message effort changes. Only Sonnet 5.5 accepts it, so a router or retry that re-sends the same body to another model must remove it first.

Sonnet 5.5 keeps high as the default effort, but the levels are recalibrated. The same name does not produce the same amount of thinking as on Sonnet 5.

On both models, thinking counts toward max_tokens even when its text is hidden. A limit sized for a no-thinking route can cut replies off. Anthropic suggests 64,000 as a starting point for long agentic coding turns. Stream any request with a limit that large.

What each thinking setting returns. Claude Opus 5.5: thinking type disabled returns a 400 at every effort level; thinking type enabled with budget_tokens returns a 400; omitting thinking or sending adaptive works because thinking is always on; set output_config.effort, which defaults to medium. Claude Sonnet 5.5: thinking type disabled returns a 400, send between_tools instead; budget_tokens returns a 400; adaptive thinking at low effort works and is the first thing to try, with a default effort of high; between_tools works only at effort high or below with no other fields. On both models, thinking counts toward max_tokens, so size the limit for thinking plus the reply.
The same setting can be a 400 on one model and fine on the other.Open full size →
Opus 5.5 (Python)
# Before (Opus 5): thinking={"type": "disabled"}
# After: thinking is always on, effort is the control
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    output_config={"effort": "low"},
    messages=[{"role": "user", "content": "Summarize this ticket."}],
)
Sonnet 5.5 (Python)
# Preferred: adaptive thinking (the default) at low effort
response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    output_config={"effort": "low"},
    messages=[{"role": "user", "content": "Summarize this ticket."}],
)

# Route must stay thinking-off: between_tools, effort high or below
response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    thinking={"type": "between_tools"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "Summarize this ticket."}],
)

Tip
Delete any prompt line that tells the model not to think. It cannot comply, and Anthropic notes such lines make internal tags more likely to leak into visible output.

04

How do you replace forced tool use?

tool_choice types any and tool return a 400 on both models. Steer with auto, strict schemas, and a check.

On Sonnet 5.5 and Opus 5.5, tool_choice: {type: "any"} and {type: "tool", name: ...} are rejected, including on the token counting endpoint. auto (the default) and none still work.

If you forced a tool to steer the model, switch to auto, say in the prompt when the tool applies, and set strict: true on the tool definition so the arguments match the schema. A strict schema needs additionalProperties: false.

auto does not guarantee a call. Check that one happened and retry or fall back if it did not.

If you forced a tool only to get JSON back, use structured outputs (output_config.format) instead.

Both models (Python)
# Before: tool_choice={"type": "tool", "name": "get_weather"}
response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    tools=[{**tool, "strict": True} for tool in tools],
    tool_choice={"type": "auto"},
    messages=[{"role": "user", "content": "What's the weather in Paris? Use the get_weather tool."}],
)

if not any(block.type == "tool_use" for block in response.content):
    ...  # retry once, or accept a text answer
05

Does your code read response blocks by type?

A response can begin with thinking blocks. Code that reads content[0].text will break.

With thinking on by default, the first block in response.content is often a thinking block, not text. Under the default display setting its text is an empty string, so a parser that grabs the first block returns nothing.

Select blocks by their type field. Handle tool_use blocks in tool loops, and check stop_reason before reading anything (step 7 covers refusals).

A second change catches chat UIs. The short notes the model writes between tool calls now come back as progress-update thinking blocks, empty by default. No request fails, but a UI that renders only text goes quiet during long agent turns. Set thinking.display to "updates" (beta header thinking-display-updates-2026-08-18) to get those notes as text. On Sonnet 5.5 with between_tools, they come back with text already.

Both models (Python)
response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Explain this function."}],
)

# Never assume content[0] is text
answer = "\n".join(
    block.text for block in response.content if block.type == "text"
)

Tip
Check your streaming handler too. Thinking blocks arrive as their own content blocks with thinking_delta events, before the text.

06

Is your conversation history append-only?

Thinking blocks are tied to the model and the conversation. Editing earlier turns can now fail the request.

Anthropic calls this preserved thinking. When you send a thinking block back, the API checks that the system prompt, the tools list, and every earlier message are byte-for-byte what they were when the block was produced. If something changed, that block and every later one are invalid.

For accounts created on or after August 31, 2026, 00:00 UTC, the API enforces this by default on Opus 5.5 and Sonnet 5.5, and the request fails with a 400. Older accounts are only checked when they opt in by setting thinking.block_binding.prefix_mismatch_behavior.

Common causes: a reminder injected into an old turn and later removed, a system prompt changed mid-session, tools added or removed between requests, and client-side summarizing that keeps newer turns with their thinking blocks.

The fix is to append instead of edit. Send assistant turns back exactly as returned. Add new instructions as a mid-conversation system message (role: "system" inside messages). Declare every tool at the start, or use the tool_addition and tool_removal blocks. For long sessions, use server-side compaction or context editing.

As a stopgap, prefix_mismatch_behavior: "drop_block" (beta header thinking-binding-controls-2026-08-01) drops the invalid blocks and lets the request succeed. The model loses that reasoning and the prompt cache restarts at the edit. On Sonnet 5.5 it works only with adaptive thinking, not between_tools.

Model and account binding: only Opus 5.5 can read Sonnet 5.5 thinking blocks, and only on the Claude API and Google Cloud. On the Claude API, only Fable 5.1 and Mythos 5.1 read Opus 5.5 blocks. Sonnet 5.5 blocks also work only in the account that produced them or a linked account. In every case the API drops blocks a model cannot read and the request still succeeds, so do not strip thinking blocks yourself.

Edit versus append with preserved thinking. Top: a conversation of system, tools, user, assistant with thinking, and user, where the first user turn is edited. The thinking block after the edit becomes invalid. On accounts created on or after August 31, 2026, the request fails with a 400; with drop_block it succeeds but the reasoning is lost. Bottom: the same conversation with a new system message and a new user turn appended at the end. The prefix is unchanged, thinking blocks stay valid, and the prompt cache keeps hitting. Append-only replacements: a role system message for new instructions, all tools declared up front or tool_addition and tool_removal for tool changes, and server-side compaction or context editing for long sessions.
Change the conversation by adding to the end, never by rewriting the middle.Open full size →
Append, don't edit (Python)
# Send the assistant turn back exactly as returned, thinking blocks included
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": "Now add tests for it."})

# New instruction mid-session: append a system message, keep system= unchanged
messages.append({"role": "system", "content": "Reply in British English from now on."})

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    system=SYSTEM_PROMPT,  # identical to the first request
    tools=TOOLS,           # identical to the first request
    messages=messages,
)

Tip
Append-only history also raises your prompt cache hit rate, so it is worth doing on older accounts that are not enforced yet.

07

What happens when Claude refuses a request?

A refusal is a normal 200 response with stop_reason "refusal", not an HTTP error. Handle it before reading content.

Both models run safety classifiers. A decline returns stop_reason: "refusal" and a stop_details object whose category names the policy area. Branch on stop_reason. stop_details is informational and can be null.

Opus 5.5 categories include cyber, bio, and reasoning_extraction. Sonnet 5.5 declines in five: cyber, bio, frontier_llm, reasoning_extraction, and general_harms. reasoning_extraction usually means a prompt asked the model to write out its internal reasoning. Remove that instruction and read summarized thinking blocks instead.

Billing depends on timing and category. Since September 24, 2026, a refusal before any output is billed when the category is bio, frontier_llm, or reasoning_extraction. Other pre-output refusals, and ones with a null category, are not billed. A mid-stream refusal bills the input and the output already streamed. Every refusal counts against rate limits.

Fallback adds a second request. When a fallback runs, you pay for it, and the refusal that triggered it is also billed if it was mid-stream or in a billed category. Fallback credit covers the fallback model's prompt cache miss.

On the Claude API, fallbacks: "default" retries on the model Anthropic recommends for the category. For Sonnet 5.5 it retries cyber and frontier_llm declines on Sonnet 5, and not the other three categories. Opus 5.5 does not retry reasoning_extraction declines. On other platforms, use the SDK's refusal fallback middleware or your own retry. The fallback model usually runs without the original thinking blocks.

Is a Claude refusal billed? A response arrives with HTTP 200. If stop_reason is not refusal, read the blocks by type as in step 5. If it is a refusal, check when it stopped. A mid-stream refusal bills the input and the output already streamed, and the partial output should be discarded. A refusal before any output is billed like any other request if its category is bio, frontier_llm, or reasoning_extraction; in any other category, or with a null category, it is not billed. If fallback is on, the fallback request is billed too, and every refusal counts against rate limits. Rules as of September 24, 2026.
Billing rules as of September 24, 2026. Anthropic may change the billed categories.Open full size →
Both models, Claude API (Python)
response = client.beta.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    betas=["server-side-fallback-2026-07-01"],
    fallbacks="default",
    messages=messages,
)

if response.stop_reason == "refusal":
    category = response.stop_details.category if response.stop_details else None
    log_refusal(category)  # don't blindly retry: some categories are billed
    # content is empty (refused before output) or partial (refused mid-stream)
else:
    ...  # read blocks by type, as in step 5

Tip
A mid-stream refusal leaves partial output in content. Discard it rather than showing it as a finished answer.

08

How do you test the migration before switching traffic?

Run a fixed task set on the old and new model, re-run the effort sweep, then roll out gradually.

Anthropic's guides say to test in a development environment and re-run your effort sweep. Effort levels do not map one-to-one from older models. For Sonnet 5.5, Anthropic suggests starting agentic coding at medium and chat at medium or low. For Opus 5.5, start at the new default of medium and test the levels on either side.

Cover these cases: plain text generation, structured output and tool calls, multi-turn conversations that replay thinking blocks, any code path that edits or summarizes history, streaming and parsing, computer use if you use it, refusal handling and fallback, and long-context tasks near your max_tokens limit.

Record for each run: task success, input and output tokens (thinking included), cache reads and writes, refusals and fallbacks, end-to-end latency including tool calls, and cost per completed task.

Judge cost per completed task, not per token. A cheaper request that needs more turns or retries is not cheaper.

Ship behind a flag or a percentage rollout, watch 400s and refusal rates, and keep the old model ID ready as a rollback.

A suggested Claude 5.5 rollout plan in five stages. 01 Audit: grep for changed parameters, step 2. 02 Fix: thinking, tool_choice, parsing, and history, steps 3 to 7. 03 Evaluate: the same tasks on the old and new model plus an effort sweep, in a development environment. 04 Canary: a small share of traffic behind a flag while you watch 400 errors and refusal rates. 05 Roll out: ramp up gradually, monitor errors, and keep the old model ID as a rollback. Measure on every run: task success rate, tokens with thinking included, cache reads and writes, refusals and fallbacks, latency with tool calls included, and cost per completed task.
Our suggested sequence, not an Anthropic requirement.Open full size →

Tip
Claude Code ships with a migration helper: /claude-api migrate this project to claude-sonnet-5-5 (or claude-opus-5-5). It asks for scope first and leaves a checklist of items to verify by hand. Review its diff like any other change.

Sonnet 5.5 vs Opus 5.5: what breaks on each

Claude Sonnet 5.5Claude Opus 5.5
Thinking: "disabled" returns a 400. Use between_tools (effort high or below) for thinking-off routes.Thinking: always on. "disabled" and budget_tokens return a 400 at every effort level.
Default effort: high, with recalibrated levels.Default effort: medium (Opus 5 was high).
Forced tool_choice any / tool: 400.Forced tool_choice any / tool: 400.
Computer use: computer_toolset_20260801 on the Claude API and Google Cloud.Computer use: computer_toolset_20260801 on the Claude API and Google Cloud.
Advisor tool: rejects Opus 4.8, Opus 4.7, and Sonnet 5 advisors.Advisor tool: no new restriction listed.
Thinking blocks: read only by Opus 5.5 (Claude API, Google Cloud). Account-bound.Thinking blocks: read only by Fable 5.1 and Mythos 5.1 on the Claude API.
Refusal categories: cyber, bio, frontier_llm, reasoning_extraction, general_harms.Refusal categories: cyber, bio, reasoning_extraction.

Both models enforce the history-editing check by default for accounts created on or after August 31, 2026. Do not reuse one code sample for both: the thinking settings that fix one model are a 400 on the other.

Will Claude 5.5 cost more or less?

ModelInput / output / cache read (per million tokens)
Claude Opus 5$5 / $25 / $0.50
Claude Opus 5.5$4 / $20 / $0.20
Claude Sonnet 5$2 / $10 / $0.20
Claude Sonnet 5.5$2 / $10 / $0.10

Opus 5.5 is 20% cheaper per token than Opus 5. Sonnet 5.5 matches Sonnet 5 except for cache reads, which Anthropic cut to $0.10 per million tokens on October 7. Cache writes are unchanged on both lines. Prices are from Anthropic's pricing page on October 22, 2026, so check it again before you budget.

List price is only part of the bill. Thinking tokens bill as output, the default effort changed on Opus 5.5, billed refusals and fallbacks add requests, and a cheaper cache read rewards append-only history more than before. Measure cost per completed task on your own workload.

Do you also need API version 2026-10-21?

That is a separate upgrade. On October 21, 2026 Anthropic released API version 2026-10-21 with new major SDKs (Python 2.0.0, TypeScript 1.0.0, and matching releases for the other languages). Those SDKs send the new version by default.

The new version returns a 400 for temperature, top_p, and top_k, for document blocks in assistant messages, and for citations on user text blocks. The SDKs also change some types and how API keys are sent. Keep the two migrations in separate changes so a failure points at one cause.

Does the GitHub Copilot deadline affect you?

Only if you use GitHub Copilot. GitHub announced on October 15 that Claude Opus 4.8 and Claude Opus 5 leave Copilot on November 16, 2026, with Claude Opus 5.5 as the suggested replacement. Individual subscribers on annual plans keep Opus 4.8. Our Copilot retirement guide covers that migration.

The date does not retire those models on Anthropic's API. Direct API users should follow Anthropic's model deprecations page. The nearest API date there is for Claude Sonnet 4.5 (claude-sonnet-4-5-20250929), which retires on the Claude API on November 30, 2026, with Sonnet 5.5 as the recommended replacement.

The trade-offs worth knowing

  • Less control over thinking: Opus 5.5 has no off switch, and Sonnet 5.5's between_tools comes with effort and field limits. Latency-sensitive routes need measurement, not a flag.
  • Append-only history is a design constraint: harnesses that rewrite context to save tokens need rework, not a one-line fix.
  • Model switches lose reasoning: routers and fallbacks that move a conversation between models run without the earlier thinking blocks, which can cost quality and tokens on the next turn.
  • Refusals cost money in some categories: a retry loop on every refusal can add billed requests without changing the answer.
  • Third-party platforms lag: server-side fallback is Claude API only for Sonnet 5.5, Bedrock keeps the older computer use tool, and Foundry hosts Sonnet 5.5 on Azure only, without some features.

Pre-production checklist

  • Source and target model IDs confirmed for each route and platform.
  • Disabled thinking, budget_tokens, and forced tool_choice removed.
  • Effort set explicitly and re-tuned with a sweep.
  • max_tokens sized for thinking plus the reply.
  • Responses and streams parsed by block type.
  • Thinking blocks passed back unchanged, history append-only.
  • stop_reason "refusal" handled, fallback configured, billing reviewed.
  • Tool use and computer use flows retested.
  • Regression set passed, latency and cost compared with the baseline.
  • Gradual rollout with error monitoring and a written rollback step.
Personal verdict

Start with the grep in step 2 and the parser fix in step 5. They cover the failures you will hit on the first request. Then spend real time on step 6. A removed parameter fails loudly and immediately, but a harness that edits history only fails on new accounts or after you opt in, which is exactly when you least want to find it. If your app runs on Opus 5, Opus 5.5 is the easy call: a lower list price and a short list of request changes, all covered above. On Sonnet 5, move to Sonnet 5.5 after a proper effort sweep, because the recalibrated levels are where quality and cost move most.

Frequently asked questions

Is Claude 5.5 one model?+

No. Claude Sonnet 5.5 (claude-sonnet-5-5) and Claude Opus 5.5 (claude-opus-5-5) are separate models with separate migration guides, prices, and breaking changes. Claude Haiku 5.5 is a third model with its own guide.

Can I turn off thinking on Claude Opus 5.5?+

No. Opus 5.5 returns a 400 for thinking type disabled and for manual budgets. Lower output_config.effort, starting at low, to reduce thinking, latency, and cost. On Sonnet 5.5 you can send thinking type between_tools at effort high or below.

Why do I get a 400 error after editing my conversation history?+

On accounts created on or after August 31, 2026, Opus 5.5 and Sonnet 5.5 reject a request that replays a thinking block after an earlier part of the conversation changed. Keep history append-only, or set prefix_mismatch_behavior to drop_block as a temporary workaround.

Am I charged when Claude refuses a request?+

Sometimes. A refusal before any output is billed when its category is bio, frontier_llm, or reasoning_extraction, and not otherwise. A refusal mid-stream bills the input and the output already streamed. A fallback request is billed on top.

Should I strip thinking blocks before switching models?+

No. Pass them back unchanged. The API drops blocks the target model cannot read, does not bill them, and the request succeeds. Removing them yourself can cause ordering errors and loses reasoning if the conversation returns to a model that can read them.

Does the GitHub Copilot November 16 deadline apply to the Anthropic API?+

No. It applies only inside GitHub Copilot. Anthropic publishes its own retirement dates on its model deprecations page.

Sources & further reading

Sources and further reading

More practical field notes from Agent Builders HQ are on the way.

Stay tuned →