Agent Upstart

Cool things people are building with agents — and practical help getting the most out of them.

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

  1. 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.
  2. 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.
  3. 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 in output_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 is high.
  4. Remove sampling parameters. Remove temperature, top_p, and top_k from requests. The deprecations page records that they were removed in API version 2026-10-21 and 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.
  5. 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.
  6. Replace forced tool choice with auto and strict tools. Sonnet 5.5 rejects tool_choice of type any or tool with a 400 error. Send tool_choice: {"type": "auto"} and mark the tool strict: true so its input matches the schema — and say in the prompt when to use the tool, because the model can now answer without calling it.
  7. Handle thinking in responses. A response can start with thinking blocks, so code that reads content[0].text breaks. Read content blocks by type, pass thinking blocks back unchanged in tool-use loops including empty ones, and revisit max_tokens — it covers thinking plus text, and thinking tokens are billed as output. Thinking text is omitted by default; set display: "summarized" if you show it. To run without up-front thinking, send thinking: {"type": "between_tools"} at high effort or below — disabled returns a 400 on Sonnet 5.5, and between_tools takes no other field.
  8. Clear the remaining 4.5-era settings. Remove any context-window beta header. Remove the interleaved-thinking-2025-05-14 header. Replace fine-grained-tool-streaming-2025-05-14 with eager_input_streaming: true on each tool that needs it. Move output_format to output_config.format — the old parameter is deprecated and returns a 400 without the structured-outputs-2025-11-13 beta header. On Bedrock, move computer use from computer_20250124 to computer_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.
  9. 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 high unless 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.
  10. 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

Limits

Related playbooks

Sources

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