A Claude Opus 5.5 migration looks like a one-line change. Swap claude-opus-5 for claude-opus-5-5, redeploy, enjoy the lower price. For a plain chat integration that is roughly true. For anything that uses tools, manages conversation history, or streams output to a user, it is not.
Anthropic’s what’s new page lists four breaking changes, each of which returns a 400 error for a request pattern that worked on Opus 5. It also lists four behavior changes that raise no error at all, which makes them harder to catch. This is the working list, with the error text you will see and what to change.
For what the model is, what it costs and where the 40% saving comes from, start with our Claude Opus 5.5 launch coverage. This post assumes you have decided to move and want to know what will break.
opus alias and the default model setting both now resolve to Opus 5.5 on subscription plans, the API, Bedrock and Google Cloud. Microsoft Foundry is the exception. If your developers run Claude Code on defaults, they have been on Opus 5.5 since September 22. That affects their sessions, not your production code, but it is worth telling them.
Break 1: thinking can no longer be turned off
On Opus 5 you could send thinking: {"type": "disabled"} to skip reasoning entirely, or thinking: {"type": "enabled", "budget_tokens": N} to cap it at a fixed budget. On Opus 5.5, both return a 400 invalid_request_error. The message is explicit:
"thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.The same message appears with thinking.type.enabled in place of thinking.type.disabled.
Who hits this. Teams that turned thinking off to save cost and latency on simple, high-volume work: tagging content, classifying support tickets, extracting fields from forms, writing alt text. It was a sensible optimization on Opus 5. It is now an error.
The fix. Remove the thinking field, or send thinking: {"type": "adaptive"}, and control depth through effort instead. Set effort to low for the work you previously ran without thinking. Anthropic says that at its lowest effort setting Opus 5.5 caught 72% of known bugs in its code review tests against 56% for Opus 5 at high effort, so low is not a crippled mode. Measure the latency on your own traffic, because it will not be zero.
Claude Fable 5.1 has the same restriction, so if you already moved something to Fable 5.1 you have met this one.
Break 2: forced tool use is gone
tool_choice: {"type": "any"} and tool_choice: {"type": "tool", "name": "..."} now return:
tool_choice: type "tool" and "any" are not supported for this model.auto, which is the default, and none still work. Fable 5.1 has the same restriction.
Who hits this. Any pipeline that forces a tool call to guarantee structured output. It was a common pattern: define an extract_fields tool, force it, and read the arguments as your JSON. Content migration scripts, form processors and metadata generators often work this way.
The fix. If what you wanted was guaranteed JSON, use structured outputs, which constrain the response to a schema without needing a tool at all. If you genuinely need a tool call, leave tool_choice on auto, make the instruction clear, and turn on strict tool use so the arguments match your schema when the call happens. Then handle the case where the model answers in text instead, because auto means it can.
Break 3: thinking blocks are now tied to their model and conversation
This one needs the most care, because whether it breaks depends on when your account was created.
Thinking blocks returned by the API are meant to be passed back in later turns. On Opus 5.5 they are bound in two ways.
Bound to a model family. Opus 5.5 reads thinking blocks produced by Opus 5, earlier Opus models, and Sonnet and Haiku models. It does not read thinking blocks produced by Claude Fable or Claude Mythos. If you route a conversation between Fable 5.1 and Opus 5.5, for example by using Fable for hard turns and Opus for the rest, the Fable thinking blocks will not carry over. On the Claude API only, Fable 5.1 and Mythos 5.1 can read Opus 5.5 blocks, so the restriction runs in one direction.
Bound to the conversation prefix. The API now checks whether the system prompt, the tool definitions or any earlier message has changed since a thinking block was produced. If it has, and you replay the block, then:
- For accounts created on or after August 31, 2026, 00:00 UTC, on the Claude API and cloud platforms, the request returns a 400 error by default.
- For older accounts, nothing changes unless you opt in.
To control this, send the beta header thinking-binding-controls-2026-08-01 and set thinking.block_binding.prefix_mismatch_behavior to "drop_block". The API then drops the stale block instead of rejecting the request. Older accounts can opt in to either behavior with the same field.
Who hits this. Anything that edits conversation history before resending it: trimming old turns to save tokens, redacting personal data from earlier messages, rewriting the system prompt per turn with the current date or user’s name, or adding and removing tools as a conversation moves between stages.
The agency trap. The account creation date is the part to watch. If you set up a fresh API account for a client this month, that account gets the strict behavior by default. Your own agency account, created last year, does not. The same code can pass every test in your environment and fail in the client’s. Either set prefix_mismatch_behavior explicitly in both, or test against an account created after August 31.
If you need to change instructions partway through a conversation, mid-conversation system messages are supported on Opus 5.5 and add to the conversation rather than editing its start. Test that path before you rely on it, but it is the more natural fit for the new rules than rewriting the system prompt.
Break 4: the older computer use tool is rejected on two platforms
On the Claude API and Google Cloud, Opus 5.5 supports only the computer_toolset_20260801 computer use tool. Declaring computer_20251124 returns:
'claude-opus-5-5' does not support tool types: computer_20251124.On Amazon Bedrock, computer_20251124 still works. If you already use the toolset version, nothing changes.
Who hits this. Browser automation and form-testing agents built last year, and, more awkwardly, code that runs on more than one platform. A single integration that works on Bedrock and fails on the Claude API with the same model ID is a confusing bug to chase. Move to the toolset version everywhere, rather than branching on platform.
Quiet change 1: your streaming interface may go silent
This is the change most likely to produce a support ticket from a client rather than a failed test.
Short notes the model writes between tool calls ("Checking the order history now," "Found three matching records") used to arrive as text blocks. On Opus 5.5 they arrive as progress-update thinking blocks. At the default display: "omitted" setting, those blocks have an empty thinking field.
No error is raised. If your interface streams text blocks to the user, it now shows nothing between tool calls, which on a long agent run looks exactly like a hung request. The final answer still arrives as text.
The fix. Anthropic’s thinking documentation on progress updates covers the display setting that returns the text of these blocks. Change it, or render a generic working indicator while tool calls are in flight. Either way, test a multi-step tool run in the real interface, not just the API response.
Quiet change 2: the default effort dropped to medium
Opus 5 defaulted to high effort. Opus 5.5 defaults to medium. Any request that does not set effort now runs at medium.
That default is the source of most of the advertised cost saving, and for many tasks it will be fine. It also means a side-by-side test that sets nothing is not comparing like with like. If you tuned prompts against Opus 5 on its default, set high explicitly on Opus 5.5 for the first comparison, then step down and see where quality holds.
Per-message effort is available as a beta, so a conversation can run most turns at medium and raise effort for the one turn that needs it.
Quiet change 3: more thinking per turn, so leave room in max_tokens
Anthropic says that at the same effort setting, Opus 5.5 "tends to think more per turn" than Opus 5, most noticeably at xhigh and max. Thinking tokens count against max_tokens.
If your max_tokens value was sized to fit Opus 5’s thinking plus a known answer length, Opus 5.5 can run out partway through the answer. Watch for stop_reason: "max_tokens" in your logs after switching, and raise the limit where it appears. Remember that raising it also raises what a runaway request can cost.
Quiet change 4: new refusal categories that return HTTP 200
Opus 5.5 runs a biology safety classifier alongside the existing cybersecurity one, and adds a reasoning_extraction category for requests that push the model to reproduce its internal reasoning. When either declines a request, the API returns HTTP 200 with stop_reason: "refusal" and a stop_details object naming the policy area.
Why that matters. Code that treats any 200 response as success will pass a refusal straight through to a user or into a database. Check stop_reason on every response, not just the status code.
The reasoning_extraction category deserves a look if you ask the model to "show all of your reasoning" in its visible output for audit purposes. Ask for a stated rationale or a summary of the steps instead. See Anthropic’s refusals and fallback documentation for handling.
Smaller changes worth knowing
Caching minimum. The minimum cacheable prompt is 512 tokens. Combined with a 60% lower cache read price, shorter system prompts are now worth caching.
Fast mode is Claude API only. The research preview uses the beta header fast-mode-2026-02-01 and speed: "fast", at $8.00 input and $40.00 output per million tokens. It is not available on Bedrock, Claude Platform on AWS, Google Cloud or Foundry.
Two new betas. Tools can now be defined inside a message, using a tool_addition block in a mid-conversation system message with the header inline-tools-2026-09-15. Compaction on demand, with the header compact-2026-09-04, returns a signed compaction block that summarizes the conversation so far. Both are useful for long agent runs. Both are betas, so do not build a client deliverable on them without a fallback.
Model ID differs on Bedrock. It is anthropic.claude-opus-5-5 there, with regional inference profiles. Everywhere else it is claude-opus-5-5.
A Claude Opus 5.5 migration checklist, in order
- Search your code for
"type": "disabled",budget_tokens,tool_choiceset toanyortool, andcomputer_20251124. Each is a hard failure on Opus 5.5. - Find every place conversation history is edited before resending: trimming, redaction, per-turn system prompts, changing tool lists. Decide on
prefix_mismatch_behaviorand set it explicitly. - Check account creation dates for every account the code runs under, including client accounts.
- Set effort explicitly on every request. Start at
highfor comparison with Opus 5, then step down. - Raise
max_tokenswhere your logs show truncation. - Check
stop_reasonon every response and handlerefusal. - Test the real interface on a multi-step tool run and confirm users can see progress.
- Switch a slice of traffic first. Compare tokens per request and output quality against Opus 5 before moving everything.
Opus 5 is not being retired soon. It is listed as active (legacy), with retirement not sooner than July 24, 2027. There is no deadline forcing a rushed migration, and a staged one is cheaper than an outage.
Frequently Asked Questions
Is a Claude Opus 5.5 migration just a model ID change?
For a basic chat integration with no tools, no thinking settings and no history editing, mostly yes. For anything using forced tool calls, disabled thinking, edited conversation history or the older computer use tool, no. Those return 400 errors.
Why does my request fail with “thinking.type.disabled is not supported”?
Opus 5.5 always uses adaptive thinking. Remove the `thinking` field or set it to `adaptive`, and use a `low` effort setting for the work that previously ran without thinking.
How do I get guaranteed JSON without forcing a tool?
Use structured outputs, which constrain the response to a schema. If you need an actual tool call, use `tool_choice: auto` with strict tool use and handle the case where the model replies in text.
What is the thinking block prefix mismatch error?
Opus 5.5 checks whether the system prompt, tools or earlier messages changed since a thinking block was produced. If they did and you resend the block, accounts created on or after August 31, 2026 get a 400 error by default. Use the `thinking-binding-controls-2026-08-01` beta header and set `prefix_mismatch_behavior` to `”drop_block”` to drop the block instead.
Why does the same code work in my account and fail in my client’s?
Most likely the prefix mismatch rule. It applies by default only to accounts created on or after August 31, 2026, so a new client account behaves differently from an older agency account.
Can I pass Fable 5.1 thinking blocks to Opus 5.5?
No. Opus 5.5 reads thinking blocks from Opus 5, earlier Opus models, Sonnet and Haiku, but not from Fable or Mythos.
Why did my chat interface stop showing progress during tool calls?
Text between tool calls now arrives in thinking blocks that are empty by default. Change the thinking display setting or show a generic progress indicator.
Why are my Opus 5.5 responses getting cut off?
Opus 5.5 thinks more per turn than Opus 5 at the same effort, and thinking counts against `max_tokens`. Raise the limit where you see `stop_reason: “max_tokens”`.
Does Opus 5.5 return an error when it refuses?
No. It returns HTTP 200 with `stop_reason: “refusal”` and a `stop_details` object. Check the stop reason on every response.
Does the computer use change affect Bedrock?
No. Bedrock still accepts `computer_20251124`. The Claude API and Google Cloud require `computer_toolset_20260801`.
Do I have to migrate off Opus 5 now?
No. Opus 5 is active (legacy) and will not retire before July 24, 2027.
Is Claude Code already using Opus 5.5?
Yes, if it runs on the `opus` alias or the default setting, on every platform except Microsoft Foundry. To stay on Opus 5, set the model explicitly to its full ID.
