Treat a new model like a breaking change

Anthropic released Claude Haiku 5.5 on October 7. For prompts up to 100,000 tokens, its price per token is a tenth of Haiku 4.5’s (pricing). It also counts the same text as about 30% more tokens, so the same request costs closer to an eighth (Haiku 5.5 overview). When I went to move one of my projects to it, I read the docs before touching anything, and caught the breaking changes while they were still only on the page.

The request belongs to the model

A model upgrade looks like a one-line change: swap the model ID and keep everything else. That holds only while the new model accepts the same requests as the old one. Haiku 5.5 rejects settings that Haiku 4.5 accepts, so a request copied from 4.5 can come back as a 400 error.

A new model deserves the care you’d give a new major version of a library. The request body is written for one model: the sampling settings, how the conversation ends, how much the model may think. When the model changes, check that body against the new model’s docs before you send it anything.

If you run a business on an AI tool and someone suggests moving to the newer, cheaper model, ask who is going to check the requests first.

Where the habit lives

Reading the docs is what caught the changes. The other habit is about where the settings live. Every AI project I build gets an admin screen where the provider, the model, and the request settings live as data instead of code. How much that screen can do varies from project to project, but on each one the model is a setting.

Try the switch yourself

Below is an interactive recreation of that kind of screen, for a made-up app that sorts customer emails into order, question, or complaint. It makes no live API calls. Press Add Claude Haiku 5.5, which copies the working Haiku 4.5 request into a new profile, then press Send (simulated). The first thing it catches is the one-line change itself: the copied body still names claude-haiku-4-5. Use Show fix on that and on each problem after it until the request passes, then press Save to Claude Haiku 5.5.

What changed in Haiku 5.5

These are the four changes I’d check first. The Haiku 5.5 migration guide has the full list.

Sampling settings are fixed

Haiku 4.5 lets you set temperature, top_p, and top_k. On Haiku 5.5, temperature must be 1 if you send it, and top_p must be 0.99. Any top_k value is rejected, and so is a request that sends temperature and top_p together, even at those values. Each of these returns a 400 error, with thinking on or off (migration guide, thinking docs). The demo’s request sets temperature: 0, so it fails here. The simplest fix is to leave these settings out.

No more prefill

A prefill is a final assistant turn that the model continues. The demo ends its conversation with "Tag:" so the reply starts in the right format. Haiku 4.5 accepts a prefill when thinking is off. Haiku 5.5 rejects it with a 400 error, even with thinking off (migration guide). The error message the docs print says the conversation must end with a user message (errors). Ask for the format in your instructions instead.

Manual thinking budgets are gone

A request that turns thinking on with "thinking": {"type": "enabled", "budget_tokens": N} gets a 400 error from Haiku 5.5 (migration guide). The docs point to adaptive thinking instead, with thinking.type set to adaptive (errors). How much the model thinks is set with output_config.effort, which takes low, medium, high, xhigh, or max (Messages API). Haiku 5.5 defaults to medium (effort).

Thinking is on by default

This one returns no error. Haiku 5.5 uses adaptive thinking even when the request says nothing about thinking, so a response can begin with one or more thinking blocks. Thinking tokens count toward max_tokens. A request with a small max_tokens can stop with stop_reason: "max_tokens" after a thinking block and before any text (migration guide).

Your code still gets a 200, but if it reads the first content block as the answer, it can get a thinking block instead, or no text at all. The demo’s request allows 50 tokens, so the panel flags it as a warning. Its fix raises max_tokens and sets effort to low.

Before you switch

1. Read the new model’s migration guide all the way through before you change a setting.
2. Clone the profile. The new model gets its own copy of the request, and the old one stays exactly as it was.
3. Test the new profile with real requests, and check what comes back as well as the status code.
4. Keep the old profile until you trust the new one. If something goes wrong, going back means choosing the old profile again.

Exploring AI for your business?

I’m happy to compare notes. Tell me what you’re trying to do and where it’s stuck.