Claude Opus 5.5 Migration: The Changes That Pass Your Tests and Break Production
Swapping in claude-opus-5-5 surfaces two kinds of change. Four fail with a 400 on your first test run. Four more return HTTP 200 and quietly change behavior, and those are the ones that reach production. Every detail below comes from Anthropic's Opus 5.5 migration guide and launch announcement.
Breaking changes that return a 400
Claude Opus 5.5, released September 22, 2026, rejects four settings that Claude Opus 5 accepted:
Disabling thinking. thinking: {"type": "disabled"} and manual budget_tokens fail. Remove the field and set effort instead.
Forced tool use. tool_choice of any or tool fails. Use auto with strict: true (every schema object needs additionalProperties: false) and name the tool in the prompt.
Edited history. For accounts created on or after August 31, 2026, replaying a thinking block after you changed the system prompt, tools, or an earlier message fails. Keep conversations append-only.
Old computer use. computer_20251124 fails on the Claude API and Google Cloud. Use computer_toolset_20260801.
client.messages.create(
model="claude-opus-5-5", max_tokens=16000,
output_config={"effort": "low"}, # replaces thinking={"type": "disabled"}
tools=[{**t, "strict": True} for t in tools],
tool_choice={"type": "auto"}, # replaces {"type": "tool", ...}
messages=msgs)Silent changes that return HTTP 200
1. Effort defaults to medium, not high. A request that omits effort ran at high on Opus 5 and runs at medium on Opus 5.5. Output depth changes with no code change and no warning. Set effort explicitly on every request and re-run your effort sweep on your own evals.
2. Progress text moves into thinking blocks. The short notes the model writes between tool calls now arrive as thinking blocks, and at the default display: "omitted" their text is empty. A product that streams those notes to users simply goes quiet. Set thinking.display to "updates" (beta) or "summarized" and render the non-empty blocks. Code that reads content[0].text also breaks, because a thinking block can come first. Select blocks by type.
3. Thinking counts against max_tokens. Thinking now runs on every request, and max_tokens caps thinking plus visible text. A workload that ran with thinking disabled on Opus 5 can start hitting stop_reason: "max_tokens" with a cut-off answer. Anthropic suggests starting at 64k if you run at xhigh or max effort.
4. Routers and fallbacks lose the reasoning. Opus 5.5 thinking blocks can only be read by Opus 5.5 and, on the Claude API, Claude Fable 5.1 and Mythos 5.1. If your router or refusal fallback moves a conversation to Opus 5 or another model, the API drops those blocks and the request still succeeds, so the next turns run without the earlier reasoning. Anthropic also notes that server-side fallback does not retry refusals in the reasoning_extraction category.
What the cost numbers actually say
Anthropic's announcement says Opus 5.5 costs 40% less than Opus 5 on typical workloads, based on its own tests at default settings. That figure combines lower prices with fewer tokens per task, and "default settings" means medium effort on Opus 5.5 against high on Opus 5. The parts you can count on are the list prices: $4 / $20 per million input and output tokens versus $5 / $25 (20% lower), and cache reads at $0.20 versus $0.50 (60% lower). If you pin effort to high to preserve Opus 5 behavior, measure your own cost per completed task instead of budgeting on 40%. Thinking tokens bill as output even when their text is hidden.
In Claude Code, /claude-api migrate applies most of the loud fixes and returns a checklist for the rest. The quiet ones still need an eval and a canary before production traffic moves.
Planning your move to Opus 5.5?
TriSeed runs the eval, effort sweep, and cost-per-task check before your production traffic moves.
Comments