Claude 5.5 migration: the old requests that now return 400

Claude Opus 5.5 (September 22, 2026) costs $4/$20 per million tokens, down from Opus 5’s $5/$25. Claude Sonnet 5.5 (September 28, 2026) keeps Sonnet 5’s $2/$10.

Neither is a drop-in swap. Anthropic lists four breaking API changes for Opus 5.5 and five for Sonnet 5.5, and each one fails loudly with an HTTP 400. One more change fails silently: streaming UIs go quiet between tool calls.

Definitions

• Effort - the output_config.effort setting (low to max) that controls how much the model thinks.
• between_tools - Sonnet 5.5’s lowest thinking setting: no thinking up front, short progress notes between tool calls.
• Forced tool use - tool_choice set to any or to a named tool, which makes the model call a tool instead of replying.
• Adaptive thinking - the model decides per request how much to think; you steer it with effort, not a token budget.
• strict: true - a tool setting that makes the model’s tool input match the tool’s JSON schema exactly.
• Structured outputs - a request mode that constrains the reply itself to a JSON schema.
• Advisor tool - a beta tool that lets the model consult a second model during a turn.
• Append-only history - never editing or deleting earlier turns; new instructions go at the end.
• MTok - one million tokens.

What shipped

Anthropic’s launch claims: Opus 5.5 “generates output more than 30% faster than Opus 5” and “costs 40% less to run than Opus 5” at default settings on typical workloads. Sonnet 5.5 “runs 30%+ faster” and “costs up to 30% less for most work”. These are per-task claims from the launch pages. The per-token saving is only on Opus: 20% on input and output, and cache reads drop from $0.50 to $0.20 (60%).

What breaks: the 400s

Anthropic counts “thinking can’t be disabled” as one change; the table splits it into its two request shapes.

The exact error for forced tool use, identical on both models:

tool_choice: type "tool" and "any" are not supported for this model.

On Sonnet 5.5, between_tools has sharp edges of its own. It takes no other field (display, budget_tokens or block_binding alongside it returns a 400), it returns a 400 at xhigh and max, and it prevents changing effort on individual messages. To vary effort per turn, use adaptive thinking instead.

What breaks silently: progress text

On both models, the notes the model writes between tool calls arrive as thinking blocks, not text blocks. At the default display: "omitted" their text is empty, so a UI that streams those notes to users goes quiet mid-turn with no error. Two fixes:

• Adaptive thinking: set thinking.display to "updates" (beta, thinking-display-updates-2026-08-18 header) to get a short summary of each note.
• Sonnet 5.5 only: between_tools returns the notes with their summary text and needs no display field.

A related trap on both models: a response can now start with a thinking block, whether you use adaptive thinking or between_tools. Code that reads content[0] as the answer breaks. Select blocks by type.

Migration checklist

Opus 5 to Opus 5.5:

1. Change the model ID to claude-opus-5-5.
2. Remove thinking: disabled and budget_tokens; set effort explicitly, because the default fell from high to medium.
3. Replace forced tool_choice with auto plus strict: true.
4. Move computer_20251124 to computer_toolset_20260801 on the Claude API and Google Cloud.
5. Set thinking.display if users see text between tool calls.
6. Keep conversations append-only.

Sonnet 5 to Sonnet 5.5:

1. Change the model ID to claude-sonnet-5-5.
2. Replace thinking: disabled with between_tools, at high effort or below.
3. Replace forced tool_choice with auto plus strict: true.
4. Move computer_20251124 to the toolset on the Claude API and Google Cloud.
5. Swap any Opus 4.8, Opus 4.7 or Sonnet 5 advisor.
6. Set thinking.display if users see text between tool calls (not needed with between_tools).
7. Re-run your effort sweep: the levels are recalibrated even though the default is still high.

Refusals

Both models run safety classifiers. A decline is HTTP 200 with stop_reason: "refusal" and a stop_details category. Server-side fallback (a beta option that re-runs a declined request on another model) covers only some categories:

The practical risk is reasoning_extraction: any prompt that asks the model to write its reasoning into the response can now be refused, and fallback won’t rescue it. See why “show your reasoning” gets refused and the wider refusal-as-contract pattern.

Prompts, not just requests

The API changes are half the migration. The other half is prompt text written for older models: “minimize tool calls”, “include your reasoning”, “don’t think”. Claude 5.5 prompt audit: the bad lines weren’t there covers which lines the 5.5 guides retire and what Claude Code’s /doctor prompt-audit actually found on a real repo. Run the audit twice, since one pass can miss findings; “minimize tool calls” is the line to delete first.

Bottom line

Opus 5.5 is the cheaper Opus, and Sonnet 5.5 is the faster Sonnet at the same price. Both punish request code that disables thinking or forces tools, and both change the shape of streamed responses. Update the request code first, then the prompts. For the tier decision itself, start from why most agents default to the wrong Claude tier, and see how effort and thinking settings work for the lever that replaces disabled thinking.