Claude Sonnet 4.5 retires Nov 30: what breaks on 5.5

Claude Sonnet 4.5 stops working on the Claude API on November 30, 2026, so treat Nov 30 as a hard deadline. Anthropic's recommended replacement is claude-sonnet-5-5. Changing the model string is not enough. Five request settings that Sonnet 4.5 accepts return a 400 error on Sonnet 5.5, and thinking now runs by default, which can turn a price cut into a price rise.

This post gives you three things: a scanner script that finds the breaking settings in your repo, a cost table that shows when the cheaper per-token price still costs you more, and the exact order to migrate in.

What do I have to do before November 30?

Replace every claude-sonnet-4-5-20250929 model ID with claude-sonnet-5-5 before November 30, 2026. Then fix the settings that now return errors. The Anthropic model deprecations page lists the retirement date and the replacement. Anthropic notified developers on September 30, 2026, which gave developers 61 days of notice.

The short checklist, in the order that avoids debugging surprises:

1. Run the scanner below to list every affected line.
2. Remove temperature, top_p and top_k.
3. Replace thinking: {"type": "enabled", "budget_tokens": N} with an effort level.
4. Replace assistant prefill with structured outputs or a system prompt instruction.
5. Read response content blocks by type, never by position.
6. Re-run your evaluations and re-baseline cost.

Each step is explained below with the error text you will see if you skip it.

What is Claude Sonnet 5.5?

Claude Sonnet 5.5 is Anthropic's mid-tier model, priced at $2 per million input tokens and $10 per million output tokens. Anthropic describes it as the best combination of speed and intelligence in the Claude 5 family. Its API ID is claude-sonnet-5-5, and its context window is 1 million tokens.

Claude Sonnet 4.5 is the older mid-tier model, priced at $3 per million input tokens and $15 per million output tokens. Its API ID is claude-sonnet-4-5-20250929. Anthropic's pricing page marks it as deprecated.

The list price on Sonnet 5.5 is one third lower, per the Claude pricing page. The real bill depends on three other changes covered later: a new tokenizer, default thinking, and larger image token counts.

Which settings return a 400 error on Sonnet 5.5?

Five settings that Sonnet 4.5 accepts are rejected by Sonnet 5.5, according to Anthropic's Sonnet 5.5 migration guide. Each one returns an invalid_request_error, so a missed setting fails loudly in testing rather than silently in production.

Setting on Sonnet 4.5	What happens on Sonnet 5.5	Fix
thinking: {"type": "enabled", "budget_tokens": N}	400 error	Use adaptive thinking and output_config.effort
temperature, top_p, top_k	400 error	Remove them
Assistant prefill (last message from the assistant)	400 error	Structured outputs or system prompt
Forced tool_choice	400 error	Use auto with strict tools
thinking: {"type": "disabled"}	400 error	Use between_tools

The thinking budget error reads: "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

The prefill error reads: This model does not support assistant message prefill. The conversation must end with a user message.

Anthropic notes there is no fixed mapping from a thinking budget to an effort level. Run your evaluations at two or three effort levels and pick the cheapest one that passes.

How do I find every affected line in my repo?

Run the scanner script below from the repo root. It greps for the retiring model ID and for each setting that breaks on Sonnet 5.5. It takes one argument, the path to scan, and prints a labelled section per risk.

#!/usr/bin/env bash
# Usage: ./scan-sonnet-45.sh path/to/repo
root="${1:-.}"
check() { # label, regex
  printf '\n== %s\n' "$1"
  grep -rnE --include='*.py' --include='*.ts' --include='*.tsx' --include='*.js' --include='*.mjs' \
    --include='*.json' --include='*.yaml' --include='*.yml' --include='*.env*' \
    --exclude-dir=node_modules --exclude-dir=.git "$2" "$root" || echo "  (none)"
}
check "Pinned retiring model ID"        'claude-sonnet-4-5(-20250929)?'
check "Thinking budget (400 on 5.5)"    'budget_tokens|"type": *"enabled"|type: *.enabled.'
check "thinking disabled (400 on 5.5)"  'thinking.{0,20}disabled'
check "Sampling params (400 on 5.5)"    '(temperature|top_p|top_k) *[=:]'
check "Forced tool choice"              'tool_choice.{0,40}("any"|"tool"|any|tool)'
check "Beta headers to remove"          'interleaved-thinking-2025-05-14|fine-grained-tool-streaming-2025-05-14|token-efficient-tools|output-128k'
check "Deprecated output_format"        'output_format'
check "First-block text read"           'content\[0\]\.(text|\.text)|content\[0\]\["text"\]'
check "Possible assistant prefill"      'role.{0,6}assistant.{0,80}(prefill|\{|\[)'

Test setup. We ran the scanner on a 15-line Python fixture written to contain one instance of each risk (our lab, 2026). It flagged the model ID, the thinking budget, the temperature setting, the forced tool choice, the beta header, the first-block text read and the assistant prefill. It reported "(none)" for the two risks the fixture did not contain.

That is seven of seven planted risks found, with no false negatives on that fixture. The "possible prefill" check is a heuristic. It matches an assistant-role message near a brace or bracket, so expect some false positives and read each hit.

The scanner is a grep, not a parser. It will miss a model ID built from string parts or loaded from a database. Search your config store and your environment variables too.

Why does thinking change the bill?

Sonnet 5.5 runs adaptive thinking on any request that has no thinking field. Sonnet 4.5 ran without thinking in that case. Thinking tokens are billed as output tokens, according to the Sonnet 5.5 migration guide, so a request that used to return 400 tokens may now bill for hundreds more.

The migration guide lists the thinking defaults by model:

Model	Thinking with no thinking field	Default display
Claude Sonnet 5.5	On	omitted
Claude Sonnet 4.5	Off	summarized

Two further changes raise token counts. Sonnet 5.5 uses a new tokenizer that produces about 30 percent more tokens for the same text, per Anthropic. It also uses a high-resolution image tier. A 2000×1500 image costs about 2.5 times as many tokens on Sonnet 5.5, per the same guide.

Prompt caching moves the other way. A cache read costs $0.10 per million tokens on Sonnet 5.5 and $0.30 on Sonnet 4.5. With 30 percent more tokens, the effective cache-read cost is still about 57 percent lower (our calculation, 2026).

When does Sonnet 5.5 cost more than Sonnet 4.5?

Sonnet 5.5 costs about 13 percent less than Sonnet 4.5 when thinking adds nothing, and it costs more once thinking adds more than roughly 90 to 360 tokens per request, depending on your input size. We worked this out from the published prices and the 30 percent tokenizer figure.

Method. For each workload we priced Sonnet 4.5 at $3 and $15 per million tokens. We priced Sonnet 5.5 at $2 and $10, multiplied input and output text tokens by 1.3, then added extra thinking tokens as output. The workloads are illustrative profiles, not measurements of your traffic.

Workload	Input / output tokens	Sonnet 4.5 per 1,000 requests	Sonnet 5.5, no thinking	Sonnet 5.5, +200 thinking	Sonnet 5.5, +400 thinking	Break-even thinking tokens
Short chat	800 / 300	$6.90	$5.98	$7.98	$9.98	92
Agent step	3,000 / 400	$15.00	$13.00	$15.00	$17.00	200
RAG answer	6,000 / 600	$27.00	$23.40	$25.40	$27.40	360

The pattern is simple. Cheap, short requests are the most exposed. Consider a support chatbot that answers in two sentences. A short chat request breaks even at only 92 extra thinking tokens, so default thinking raises that bill by 16 percent at 200 thinking tokens and 45 percent at 400 (our calculation, 2026). A long RAG request absorbs 360 extra tokens before it costs more.

Sonnet 5.5 beats Sonnet 4.5 on every profile with zero thinking, and loses on the short chat profile at 200 tokens. The chart plots the table above.

If your traffic is short and high volume, set a low effort level or use between_tools. If it is long-context work, default thinking probably costs you little.

How do I turn thinking off or keep it small?

Send thinking: {"type": "between_tools"} to get the lowest thinking setting on Sonnet 5.5. Without tools, the response then contains only text. With tools, short progress updates between tool calls still come back as thinking blocks. Do not send thinking: {"type": "disabled"}. It returns a 400 error on this model.

The error text is: To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}.

Pair that with an explicit effort level. Sonnet 4.5 has no effort parameter, so Anthropic's checklist says to set output_config.effort explicitly. A request that works as written on Sonnet 5.5 looks like this:

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": prompt}],
    output_config={"effort": "medium"},
)
for block in response.content:
    if block.type == "text":
        print(block.text)

Notice the loop. A response can now start with a thinking block, so code that reads content[0].text breaks. Read blocks by type.

Also revisit max_tokens. It covers thinking plus text. For example, a limit that fit your old answers can now cut a response off mid-sentence.

How do I replace assistant prefill?

Replace each prefill according to what it was doing. Anthropic's Anthropic checklist by starting model gives five replacements: structured outputs for format, a system prompt line for preambles, clear user instructions for refusals, a user message for continuations, and the user turn for context reminders.

The most common case is the opening brace trick, where the last assistant message is { to force JSON. Use structured outputs instead. The output_format parameter is deprecated, and output_config.format replaces it. Without the beta header, output_format returns a 400 error.

For classification, Anthropic suggests tools with enum fields. That also fixes the next problem, because forced tool choice is not supported on Sonnet 5.5 either. Use auto with strict tools.

Which beta headers should I delete?

Delete interleaved-thinking-2025-05-14, because adaptive thinking interleaves automatically. Replace fine-grained-tool-streaming-2025-05-14 with eager_input_streaming: true on each tool that needs it. Remove any context-window beta header, since Sonnet 5.5 has the larger window without one. Anthropic's guide also lists token-efficient-tools-2025-02-19 and output-128k-2025-02-19 for removal if you started from Sonnet 4 or earlier.

Parse tool call input with a standard JSON parser. Anthropic warns that escaping in tool arguments can differ from Sonnet 4.5. A hand-rolled regex over raw tool input is the likeliest thing to break.

If you use computer use on Amazon Bedrock, move from computer_20250124 to computer_20251124.

Does the Claude Agent SDK or a framework hide any of this?

Frameworks hide some of it and expose the rest. Anthropic says Claude Managed Agents users need no changes beyond updating the model name. For the Messages API, your code owns every setting above.

Third-party frameworks vary. If a framework injects temperature by default, Sonnet 5.5 will reject its requests even though you never wrote the setting. Check the framework's changelog before you pin claude-sonnet-5-5. Our earlier coverage of the AI SDK 7 upgrade found that a codemod can compile cleanly while a tool still breaks, and the same lesson applies here: compiling is not passing.

The same deadline discipline applied to OpenAI's retirement of GPT-4 and o1 on October 23. Teams that waited for the cut-off day found their error handling untested. Test the failure path now, while the old model still answers.

What order should I migrate in?

Migrate in a staging environment first, change one setting per commit, and gate the switch behind a flag. The order below keeps each failure easy to attribute.

1. Pin the new model ID in staging only.
2. Remove sampling parameters and rerun your tests.
3. Replace the thinking budget with an effort level.
4. Replace prefill and forced tool choice.
5. Switch response parsing to read blocks by type.
6. Recount tokens with Anthropic's token counting endpoint and revisit max_tokens.
7. Run your evaluation set at two effort levels and compare quality and cost.
8. Roll out behind a flag at 5 percent, then 50 percent, then 100 percent.

Finish at least a week before November 30. A retired model returns errors, not a degraded answer, so there is no gradual failure to warn you.

Should I upgrade now or wait?

Upgrade now if you have any pinned claude-sonnet-4-5-20250929 reference. The deadline is fixed, the price per token is lower, and the five breaking settings are easy to find with the scanner. Waiting only shortens the time you have to run evaluations.

Wait on one thing only: the effort level. Do not guess it. Anthropic says there is no fixed mapping from a budget to an effort level, so measure on your own prompts.

If your volume is high and your requests are short, budget for the thinking cost before you celebrate the lower list price. The break-even figures in the table show how little extra thinking it takes to lose the saving.