Playbooks · Coding tasks
Move off Claude Sonnet 4.5 before it retires
Written November 2, 2026 · Edited November 12, 2026
Sonnet 4.5 retires November 30, and swapping the ID is not enough. Audit your calls, fix the five request shapes, and test on Sonnet 5.5.
What changed
On 30 September 2026, Anthropic deprecated Claude Sonnet 4.5 on the Claude API. Its model deprecations page lists the model claude-sonnet-4-5-20250929 as Deprecated, with a retirement date of 30 November 2026 and claude-sonnet-5-5 as the recommended replacement. Anthropic's own definitions are plain: a deprecated model still works but is no longer recommended, and once a model is retired, requests to it fail. The same page gives the audit route — the Usage page in Claude Console, Export, and a CSV broken down by API key and model — and says customers with active deployments get at least 60 days' notice for publicly released models.
Two wordings about the date circulate, and they do not agree. The documentation page says 30 November 2026 with claude-sonnet-5-5 as the replacement. Reports of the customer email Anthropic sent describe a different date — 24 November 2026 at 9AM PT — a different recommended replacement, Claude Sonnet 5, and reduced availability and rate errors starting 30 October. The email itself has not been published, and nothing on Anthropic's documentation pages confirms the earlier date. This page follows the documentation date and names the reported one as reported, because planning to the later date while the earlier one is possible is how a migration gets caught out. Work to the earlier date; expect the documented one.
The dates on the deprecations page apply to Anthropic-operated platforms: the Claude API, Claude Platform on AWS, Claude Models on Google Cloud where Anthropic manages them, and Microsoft Foundry. Amazon Bedrock and Google-managed Claude Models set their own retirement schedules, so the same model can retire on a different date there. A migration plan that assumes one date everywhere is wrong on at least one platform.
Why the model ID is not the whole move
Anthropic's Sonnet 5.5 migration guide lists the code changes for moving from Sonnet 4.5, and five request shapes that worked on Sonnet 4.5 return a 400 error on Sonnet 5.5. A request that leaves out those five settings works as written. The five are: thinking budgets, sampling parameters, assistant prefill, forced tool choice, and thinking: {"type": "disabled"}. Each has a replacement in the guide, and each is covered in the steps below. Two further changes do not fail requests but change results: Sonnet 5.5 runs adaptive thinking by default where Sonnet 4.5 ran none, and the same text produces about 30 percent more tokens with Sonnet 5.5's tokenizer, so budgets and max_tokens need recounting.
Steps
- Audit with the Console export. Open the Usage page in Claude Console, click Export, and review the CSV by API key and model. That is Anthropic's own audit route, and it finds the calls still naming the retiring ID — including ones in services you forgot about. Search the codebase too, for the dated ID and for the shorter alias
claude-sonnet-4-5, and check Bedrock and Google-managed deployments against their own model tables, which use their own ID forms. - Change the model ID to
claude-sonnet-5-5. The replacement has no date suffix. On other platforms use the ID listed under Availability in the migration guide — Bedrock and Google-managed deployments do not all use the same string. - Replace thinking budgets with an effort level. Sonnet 4.5 uses
thinking: {"type": "enabled", "budget_tokens": N}for all thinking. Sonnet 5.5 returns a 400 error for it. Remove the budget and set an effort level inoutput_config.effort— the guide says there is no fixed mapping from a budget to a level, so run your evaluations at two or three levels. Set the level explicitly: Sonnet 4.5 has no effort parameter, and the API default ishigh. - Remove sampling parameters. Remove
temperature,top_p, andtop_kfrom requests. The deprecations page records that they were removed in API version2026-10-21and return a 400 error; the migration guide lists them as a breaking change for 4.6-and-earlier starts. Omit them and guide behaviour through prompting instead. - Replace assistant prefills. Sonnet 5.5 rejects a prefilled last assistant turn with a 400 error; Sonnet 4.5 accepted one. Replace each prefill by what it was for: output format goes to structured outputs or tools with enum fields, preambles go in the system prompt as a request for a direct answer, continuations move to the user message, and context reminders go in the user turn.
- Replace forced tool choice with
autoand strict tools. Sonnet 5.5 rejectstool_choiceof typeanyortoolwith a 400 error. Sendtool_choice: {"type": "auto"}and mark the toolstrict: trueso its input matches the schema — and say in the prompt when to use the tool, because the model can now answer without calling it. - Handle thinking in responses. A response can start with
thinkingblocks, so code that readscontent[0].textbreaks. Read content blocks bytype, passthinkingblocks back unchanged in tool-use loops including empty ones, and revisitmax_tokens— it covers thinking plus text, and thinking tokens are billed as output. Thinking text is omitted by default; setdisplay: "summarized"if you show it. To run without up-front thinking, sendthinking: {"type": "between_tools"}athigheffort or below —disabledreturns a 400 on Sonnet 5.5, andbetween_toolstakes no other field. - Clear the remaining 4.5-era settings. Remove any context-window beta header. Remove the
interleaved-thinking-2025-05-14header. Replacefine-grained-tool-streaming-2025-05-14witheager_input_streaming: trueon each tool that needs it. Moveoutput_formattooutput_config.format— the old parameter is deprecated and returns a 400 without thestructured-outputs-2025-11-13beta header. On Bedrock, move computer use fromcomputer_20250124tocomputer_20251124; on the Claude API and Google-managed deployments, computer use goes through the toolset. Parse tool call input with a standard JSON parser — escaping can differ. - Keep conversations append-only and re-baseline cost. Sonnet 5.5's thinking blocks are signed over the conversation before them; replaying a block after editing earlier history can return a 400. Change instructions or tools with mid-conversation system messages instead. Then re-run your effort sweep — the levels are recalibrated, so start at
highunless the work is agentic or latency-sensitive — and re-baseline cost: the same text produces about 30 percent more tokens, images cost more at the higher-resolution tier, and prompt cache reads cost $0.10 per million tokens, half the Sonnet 5 rate, per the migration guide. - Test on Sonnet 5.5 before the date, per platform. Test each call site against the replacement on the platform it runs on, because Bedrock and Google-managed schedules and behaviours differ. The deprecations page itself advises thorough testing well before the retirement date. A request that stops returning 400 is not a completed migration — check the outputs, the thinking handling, and the token counts against the old model's.
Mistakes
- Planning only to 30 November. The reported email date is 24 November. Treat the earlier date as the working deadline and the documented date as the last possible day.
- Swapping the ID and shipping. Five request shapes return 400 errors. The ID change is the first step, not the migration.
- Assuming one retirement date everywhere. Bedrock and Google-managed deployments set their own schedules. Check each platform's own model table.
- Keeping
temperature: 0for determinism. Sampling parameters are removed. Determinism now comes from structured outputs and strict tools, not from a temperature setting. - Reading
content[0]as text. Responses can start with thinking blocks. Read by block type or the first block is not the answer.
Limits
- The 24 November date, the Sonnet 5 recommendation, and the reduced-availability warning come from secondhand reports of an unpublished customer email. They are stated here as reported, not as Anthropic's documented position. The documented date is 30 November 2026 with
claude-sonnet-5-5as the replacement. - No live API migration was run for this page: the checklist is the migration guide's own, read on 2 November 2026. Whether each change applies to a given call site depends on the request shapes that call site sends.
- Bedrock and Google-managed retirement dates were not read for this page — the deprecations page says those platforms set their own, and this page does not assert them.
- Prices are stated only as the migration guide states them. Re-baseline cost on your own traffic; the ~30 percent token figure is the guide's own approximation and varies with content.
Related playbooks
- Move fast-mode work off Opus 4.8 in time
- Run Sonnet with an Opus advisor in Claude Code
- Move a v6 BMad project to the v7 preview
- Move Cursor work before the OpenAI shutoff
Sources
- https://platform.claude.com/docs/en/about-claude/model-deprecations
- https://platform.claude.com/docs/en/models/sonnet-5-5/migration-guide
Back to: Coding playbooks hub · Also: Pick the cheapest model that can do the job · Move fast-mode work off Opus 4.8 in time · Re-pin Copilot models before retirements · Agent change deadlines: retirements and shutdowns