Claude Haiku 5.5 Migration Guide: Fix the 400 Errors When Moving Off Haiku 4.5

Introduction

Anthropic released Claude Haiku 5.5 on October 7, 2026, and it is not a drop-in replacement for Haiku 4.5. The model is faster and cheaper per token, but the API rejects several patterns that every Haiku 4.5 integration relies on: manual thinking budgets, non-default sampling parameters, assistant prefills, and the old computer use tool name. Each rejection arrives as an HTTP 400, so the migration feels like a series of small fires rather than one big change. This tutorial walks you through the full fix list in the order a working codebase needs it: the audit script I actually ran, the failing request shapes and their replacements, and the silent behavior changes that return 200 with the wrong answer.

Quick answer

Migrating to Claude Haiku 5.5 means swapping the model ID, deleting temperature, top_p, and top_k, replacing thinking budgets with adaptive thinking plus effort, removing assistant prefills, updating computer use tool names, and recounting tokens, because the tokenizer changed.

Evidence: what changed and why it matters

Start with the headline numbers, all as of October 2026. The official migration guide states that “the same input text produces approximately 30% more tokens on Claude Haiku 5.5 than on Claude Haiku 4.5,” because 5.5 uses the newer tokenizer shared with Claude 4.7 and later models. That one sentence has more practical impact than the headline price cut: Anthropic priced Haiku 5.5 at $0.10 input and $0.50 output per million tokens for prompts up to 100K tokens, versus $0.50 and $2.50 above that line, which is 90 percent below Haiku 4.5 under the line and 50 percent below above it. But a 90K-token prompt on 4.5 becomes roughly 117K tokens on 5.5, which lands in the upper tier and pays five times the input rate. Independent worked examples put the real saving for a long agentic turn near 35 percent, not 90. Recounting is not optional.

The performance story is real enough to make the migration worth the trouble. In customer results Anthropic published at launch, Box reported an 11-point improvement over Haiku 4.5 at about half the latency, and HubSpot’s Ze’ev Klapow said: “Haiku 5.5 was fastest to complete the task, and had the highest hit rate and the lowest false positive rate.” The model also brings a 1M-token context window, up to 128K output tokens, and, for the first time in a Haiku, an adjustable effort dial that replaces manual thinking budgets. Effort pairs well with the techniques in our Claude Code subagent effort levels guide, where per-agent effort control proved the most effective cost lever in multi-agent runs.

The breaking changes are enumerated in the official Claude Haiku 5.5 migration guide, the primary reference for everything below. It also closes the loop on model identity: the guide states that “claude-haiku-5-5 is a fixed model ID with no date suffix and no separate alias.” For prompt wording, the companion prompting guide for Claude Haiku 5.5 says existing Haiku 4.5 prompts should perform well without changes. The code breaks, the prompts mostly survive.

Prerequisites

• An integration currently calling Claude Haiku 4.5 (Python, TypeScript, or any SDK that talks to the Messages API).
• Access to the repository that holds your API calls, so you can run the audit script below.
• Anthropic API key or cloud provider access (Bedrock, Google Cloud, or Microsoft Foundry) with Haiku 5.5 available.
• Basic familiarity with the Messages API request shape: model, max_tokens, messages, tools.

Step-by-step guide

Step 1: Audit your codebase for the breaking patterns

Before touching the model ID, find every request that will 400. I ran this scanner against a sample integration and it caught all four parameter families in one pass:

#!/usr/bin/env python3
"""Scan a codebase for Haiku 4.5 patterns that 400 on Haiku 5.5."""
import re, sys
from pathlib import Path

PATTERNS = [
    ("budget_tokens", re.compile(r"budget_tokens[\"']?\s*[:=]")),
    ("temperature", re.compile(r'(?:["\']temperature["\']\s*[:=]|(?<![\w])temperature\s*=)')),
    ("top_p", re.compile(r'(?:["\']top_p["\']\s*[:=]|(?<![\w])top_p\s*=)')),
    ("top_k", re.compile(r'(?:["\']top_k["\']\s*[:=]|(?<![\w])top_k\s*=)')),
    ("computer_20250124", re.compile(r"computer_20250124")),
]

def main(root):
    hits = 0
    for path in Path(root).rglob("*"):
        if not path.is_file() or path.suffix not in (".py", ".js", ".ts", ".go", ".rb"):
            continue
        try:
            text = path.read_text(errors="ignore")
        except OSError:
            continue
        for line_no, line in enumerate(text.splitlines(), 1):
            for name, rx in PATTERNS:
                if rx.search(line):
                    print(f"{path}:{line_no}: {name}: {line.strip()[:100]}")
                    hits += 1
    print(f"\n{hits} suspicious lines found. Also check for assistant-role messages placed last in 'messages'.")
    return 0

if __name__ == "__main__":
    sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else "."))

Save it as haiku55_audit.py and run python3 haiku55_audit.py ./src. Every hit is a request that will return 400 on 5.5, so the list is also your migration work queue. Prefills need a manual pass: search for messages arrays whose last entry has role assistant.

Step 2: Swap the model ID per platform

Haiku 5.5 uses a fixed ID with no date suffix and no separate alias. Replace per platform:

One caveat for Claude Code users: since v2.1.293, the haiku alias resolves to Haiku 5.5 on the Anthropic API but still resolves to Haiku 4.5 on Bedrock, Google Cloud, and Microsoft Foundry. The Claude Code model configuration docs document this per-provider split. If your agent harness sets model: haiku, verify which provider you are on before assuming the migration is done.

Step 3: Remove temperature, top_p, and top_k

On Haiku 5.5, omit all three sampling parameters and guide the model’s behavior with prompting instead. The rules are stricter than they look: if a request includes temperature, it must be exactly 1. If it includes top_p, it must be exactly 0.99, its default. Any other value returns a 400, including a top_p of 1. Any top_k value at all returns a 400, and so does a request that includes both temperature and top_p.

That last detail bites classification pipelines hardest, because the classic Haiku 4.5 pattern was temperature=0 for deterministic labels. There is no deterministic knob anymore. Delete the parameters, keep max_tokens, and if you need stable labels, force a tool call with an enum field (Step 5) instead of lowering the temperature.

# Before (Haiku 4.5): returns 400 on 5.5
response = client.messages.create(
    model="claude-haiku-5-5",
    max_tokens=50,
    temperature=0.0,
    messages=[{"role": "user", "content": "Classify this ticket: ..."}],
)

# After (Haiku 5.5): omit sampling parameters entirely
response = client.messages.create(
    model="claude-haiku-5-5",
    max_tokens=2048,
    messages=[{"role": "user", "content": "Classify this ticket: ..."}],
)

Step 4: Replace manual thinking budgets with adaptive thinking plus effort

A thinking value of {"type": "enabled", "budget_tokens": N} returns a 400 error on Haiku 5.5. The replacement is adaptive thinking, with output_config.effort as the lever:

response = client.messages.create(
    model="claude-haiku-5-5",
    max_tokens=2048,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Summarize this thread: ..."}],
)

Adaptive thinking is on by default, so a response can begin with one or more thinking blocks even when the request does not set thinking at all. Leave thinking unset or set it to adaptive, and choose the effort level for the workload: where 4.5 ran without thinking, or with a small budget to save tokens, choose a lower effort level, since the model can skip thinking entirely on simpler requests. The effort dial is the same concept we covered in Claude Code’s dynamic workflows, where matching effort to task difficulty decided between a cheap run and a wasteful one.

Three consequences matter immediately. First, thinking tokens count toward max_tokens, so a small limit can stop with stop_reason: "max_tokens" after a thinking block and before any text. Raise small limits or lower the effort. Second, thinking blocks from earlier assistant turns stay in context and count as input tokens, where 4.5 kept only the latest turn’s, so multi-turn conversations carry more input tokens than the tokenizer change alone explains. Third, each thinking block comes back with an empty thinking field and only a signature unless you request "display": "summarized" on the adaptive thinking object.

Step 5: Replace assistant prefills with structured outputs or enum tools

A final assistant turn in messages that the model continues, a prefill, is rejected with a 400 even with thinking turned off. The fix depends on what the prefill was doing:

• Output format: use structured outputs, or tools with enum fields for classification. On Amazon Bedrock, structured outputs are not available for Haiku 5.5, so describe the format in the prompt or use a tool without strict mode and validate the output in your code.
• Preambles: ask in the system prompt for a direct answer.
• Continuations: move them into the user message, for example “Your previous response was interrupted. Continue from where you left off.”
• Context reminders: put them in the user turn.

The classification case is the most common, and the enum tool is the durable replacement for the old {"label": " prefill trick:

tools=[{
    "name": "classify_ticket",
    "description": "Classify a support ticket into one category",
    "input_schema": {
        "type": "object",
        "properties": {
            "label": {"type": "string", "enum": ["billing", "technical", "account"]},
        },
        "required": ["label"],
    },
}]

The same enum-constrained pattern feeds n8n agent pipelines; our n8n AI agents tutorial shows how such outputs slot into larger automations.

Step 6: Move computer use to the toolset

On the Claude API and Google Cloud, Haiku 5.5 supports computer use only through the computer_toolset_20260801 toolset, and a request that declares computer_20250124 returns a 400. Drop the computer-use-2025-01-24 beta header and replace the tools entry:

tools=[{"type": "computer_toolset_20260801"}]

Then change the agent loop: dispatch on each member tool_use block’s name and toolset_name rather than on input.action, handle every such block in a turn, and echo toolset_name on results. On Amazon Bedrock, use the computer_20251124 tool version with the computer-use-2025-11-24 beta header instead. Also on the API and Google Cloud, Haiku 5.5 newly supports the browser use tool (browser_toolset_20260801) for tasks inside webpages, which 4.5 did not support.

Step 7: Harden response parsing and refusal handling

Two parser habits break silently. First, because adaptive thinking is on by default, a response can start with a thinking block, so code that reads content[0] as the answer reads the wrong block. Select blocks by type. This snippet was verified against a realistic 5.5 response shape locally:

def first_text(response):
    for block in response.model_dump()["content"]:
        if block["type"] == "text":
            return block["text"]
    return ""

Second, Haiku 5.5 runs safety classifiers that can decline a request with stop_reason: "refusal", and it has no server-side fallback, so a blind retry usually refuses again. Handle it explicitly:

if response.stop_reason == "refusal":
    # No server-side fallback on Haiku 5.5: log it, surface it to the user,
    # or route the task to a larger model instead of retrying.
    handle_refusal(response)

Two more constraints from the guide: thinking blocks stay valid only while everything before them is unchanged, so keep conversations append-only and never replay thinking blocks through a different account. If you store conversations and replay them, route each one through the account that produced it.

Step 8: Recount tokens and redo the cost math

Count your prompts with model set to claude-haiku-5-5 rather than reusing 4.5 counts. Watch three budget lines: the 30 percent tokenizer inflation, the 100K-token pricing cliff (a prompt that was 90K tokens on 4.5 is roughly 117K on 5.5 and pays five times the input rate), and images, since Haiku 5.5 uses the high-resolution image tier where a 2,000 by 1,500 pixel image costs about 2.5 times as many visual tokens. Our MCP server tutorial covers similar token-budget discipline for tool-heavy pipelines.

Troubleshooting

Still getting 400s after applying every step

The most common cause is a second copy of the old parameters somewhere the audit missed: a shared request builder, a retry wrapper that re-adds temperature, or a pinned SDK version that injects defaults. Re-run the audit script from Step 1 against the full repository, including vendored helpers. If the 400s only appear on replayed conversations, check the append-only rule: sending a thinking block back after editing system, tools, or earlier messages returns a 400 on 5.5, where 4.5 ran no such check.

stop_reason “max_tokens” with no text in the response

Thinking tokens count toward max_tokens. A limit tuned for 4.5, say 50 tokens for a label, can be consumed entirely by the default-on thinking block, and the response stops before any visible text. Raise the limit to leave room for thinking, or choose a lower effort level. If you always force a tool call, the response starts with the tool call and has no thinking block at all.

A request that worked yesterday now returns stop_reason “refusal”

Haiku 5.5’s safety classifiers can decline a request with no server-side fallback, and retrying the same request usually refuses again. This is not a transient error, so do not put it on an exponential-backoff loop. Log the refusal, decide whether the content genuinely trips a safeguard, and either rephrase the request or route that task class to a different model.

Costs went up despite the cheaper list prices

This is almost always the tokenizer plus the pricing cliff. Recompute on real traffic: count the same prompts with claude-haiku-5-5, check how many cross the 100K line, and compare against the old bill. The quickest structural fix is trimming accumulated context: earlier turns’ thinking blocks now count as input tokens, so a conversation that was cheap on 4.5 can be expensive on 5.5 even before the tokenizer change. Clear old thinking blocks or compact long conversations, and keep prompts under the 100K tier where the 90 percent discount applies.

FAQ

Do prompts written for Claude Haiku 4.5 still work on Haiku 5.5?

Mostly yes. The official prompting guide says prompts written for Haiku 4.5 should perform well without changes on 5.5. What breaks are API request parameters, not prompt wording: temperature, budget_tokens, prefills, and old computer use tool names.

What effort level should I start with on Haiku 5.5?

Medium, the default. It is the first Haiku with an adjustable effort dial, so classification and extraction workloads that previously ran with a small thinking budget can try low, while multi-step agent turns stay at medium or high. Test each level against your own quality bar before committing.

Is Haiku 5.5 available on Bedrock, Google Cloud, and Microsoft Foundry?

Yes. The model ID is claude-haiku-5-5 on the Claude API, Google Cloud, Microsoft Foundry, and Claude Platform on AWS, and anthropic.claude-haiku-5-5 on Amazon Bedrock. There is no date suffix and no separate alias on any platform.

Does Claude Code already route its haiku alias to Haiku 5.5?

It depends on the provider. Since Claude Code v2.1.293, the haiku alias resolves to Haiku 5.5 on the Anthropic API, but stays on Haiku 4.5 on Amazon Bedrock, Google Cloud, and Microsoft Foundry. Check which provider your session uses before assuming the move.

Why is my bill higher after the 90 percent price cut?

Two silent changes offset the sticker price. Haiku 5.5 counts roughly 30 percent more tokens for the same text, and pricing jumps five times past a 100K-token prompt. A prompt that sat under the line on Haiku 4.5 can land above it on 5.5, so recount every prompt with the new model ID.

Conclusion

The Haiku 5.5 migration is a checklist, not a rewrite: swap the fixed model ID, delete the sampling parameters, trade budget_tokens for adaptive thinking plus effort, replace prefills with enum tools or structured outputs, move computer use to the toolset, parse responses by block type, and recount every token budget. Do it in staging first, diff a few hundred real requests between 4.5 and 5.5, and watch the refusal and cost dashboards during the rollout. If your Haiku usage lives inside Claude Code agents, read our Claude Code Projects tutorial and the Claude Code Mods guide next, since project-level memory and agent definitions are where the new effort and model-alias behavior lands.

Frequently asked questions