Claude Haiku 5.5 Migration Guide: Why Legacy Requests Fail and How to Update Existing Code

Anthropic has released Claude Haiku 5.5. This lightweight model is primarily designed for high-frequency applications sensitive to cost and latency, and can also serve as a sub-Agent alongside flagship models to handle targeted tasks.

Its key capabilities and accompanying updates include:

• Lower cost on high-frequency tasks: Average operational costs are reduced by approximately 75% compared to Haiku 4.5, targeting repetitive workloads such as summarization, context compression, database queries, and classification.
• Faster response times: The fastest Claude model at standard speeds, suited for real-time customer service and other low-latency scenarios. (Opus with Fast Mode enabled is faster.)
• Coordinating with flagship models on coding subtasks: Can operate as a sub-Agent paired with Sonnet 5.5 or Opus 5.5 to handle well-scoped work.
• First-time support for adjustable reasoning effort: The Haiku family introduces the effort setting, allowing reasoning investment to be tuned per task to balance cost against performance.
• Multiple capability upgrades: In official evaluations, computer use, knowledge work, and coding benchmarks all scored higher than Haiku 4.5.
• Price cut on Sonnet cache reads: Per-unit price halved; Anthropic estimates that total costs for most Sonnet 5.5 Agent workloads drop by about 20% as a result.
• Action support added to SDKs: Python and TypeScript SDKs gain Beta support for computer use and browser use.
• API credits for subscribers: Along with the release, Anthropic is rolling out monthly API credits to Max and Team subscribers, usable on any model across the Claude Platform.

Applications already connected to Haiku 4.5 must review request parameters, response parsing, and multi-turn conversations when upgrading to Claude Haiku 5.5. Legacy thinking configurations, sampling parameters, or assistant message prefilling may return HTTP 400 errors; code relying on positional index extraction may also fail to retrieve body text.

This official migration guide targets the Messages API (the interface for sending conversations to Claude and receiving responses). For applications using Claude Managed Agents, documentation specifies updating only the model name; existing API integrations should follow the checklist below. Users upgrading from Haiku 3.5 or Haiku 3 should also review the generational additions at the end of this guide.

For details on capabilities and pricing changes, refer to Haiku 5.5 Release Explainer. This guide focuses on updating existing code.

Upgrade Shortcut: Automated Scans with Command-Line Tools

Before manually refactoring code, if you use the official Claude Code development environment, you can use the built-in migration skill to inspect and update your code:

/claude-api migrate this project to claude-haiku-5-5

This automated tool scans your codebase, replaces model IDs, updates incompatible parameters, removes assistant message prefilling, and adjusts effort settings as needed. Before writing changes to disk, it prompts you to confirm the scope (supporting the entire workspace, subdirectories, or a specified file list); it also recognizes Amazon Bedrock and Claude on AWS client formats, automatically formatting model IDs accordingly.

The migration skill also tunes effort settings and outputs a checklist for manual verification. After automated updates, verify that requests, response parsing, and session handling conform to the rules below.

Modifying Requests: Model IDs, Thinking Configuration, and Deprecated Parameters

This layer of changes directly affects the Request Body sent to the Messages API. Several legacy patterns trigger HTTP 400 errors in Haiku 5.5 under the conditions detailed below.

1. Model ID Replacement: Unified Fixed Identifiers

Haiku 5.5 uses fixed model IDs without date suffixes and no longer offers separate latest aliases. The mappings across cloud providers are as follows:

2. Tuning Reasoning Investment with effort

• Legacy Symptom: In Haiku 4.5, enabling extended thinking was typically done via thinking: {"type": "enabled", "budget_tokens": 8000}. Passing this in Haiku 5.5 causes the API to return an immediate HTTP 400 error.
• Mechanism Change: Haiku 5.5 deprecates explicit numeric token budgets in favor of Adaptive Thinking. Control over thinking intensity moves to the output_config.effort field.
• Default-Enabled Behavior: Adaptive thinking is enabled by default. Even if your request body omits the thinking parameter entirely, the model response may contain thinking blocks. If you want the model to think less to save latency and tokens, lower the effort (e.g., "low"); at lower effort levels, the model thinks less and may skip thinking on simple requests.
• Thinking Summary Display: Haiku 4.5 returned thinking content with summary text; in 5.5, the thinking text field inside returned thinking blocks is empty by default, retaining only the signature field. If your frontend requires displaying a summary of the thinking process, you must explicitly declare thinking: {"type": "adaptive", "display": "summarized"} in the request.
• Behavior Under Forced Tool Use: If forced tool choice is configured in the request (e.g., tool_choice: {"type": "any"} or specifying a concrete tool name), Haiku 5.5 outputs tool call directives directly without generating thinking blocks. If your workflow requires the model to think before calling tools, tool choice must remain in auto mode tool_choice: {"type": "auto"}, with tool invocation timing clarified in the prompt.

3. Removing Legacy Sampling Parameters

• Legacy Symptom: Legacy code often set temperature: 0.7, top_p: 0.9, or a custom top_k. In Haiku 5.5, all of these trigger HTTP 400 validation failures.
• New Standard: Completely remove temperature, top_p, and top_k from requests, delegating output style and divergence entirely to prompt instructions.
• Strict Validation Rules:
  • If a request explicitly includes temperature, its value must be strictly 1;
  • If a request explicitly includes top_p, its value must be strictly the default 0.99 (note: even passing top_p: 1 triggers a 400);
  • Any occurrence of top_k in the request immediately returns a 400;
  • If a single request provides both temperature and top_p, even with the valid values above, it still triggers an HTTP 400 error.

4. Replacing Assistant Message Prefilling

• Legacy Symptom: In legacy implementations, applications sometimes appended an open assistant message at the end of the messages array (such as {"role": "assistant", "content": "{"} or {"role": "assistant", "content": "Sure, here is the answer:"}) to force valid JSON output or skip conversational preambles. In Haiku 5.5, using a trailing assistant message for model continuation returns an HTTP 400, even with thinking disabled. The request's messages array must end with a user message.
• Migration Strategies by Use Case:

Old pattern: guide the response with a final Assistant message
[User: "..."] -> [Assistant: "Leading text..."] -> Triggers a 400 error!

New pattern: move each requirement to the system prompt, structured interface, or user turn
├─ Strict format constraints (such as JSON) ────> Use Structured Outputs or tool definitions with Enum constraints
├─ Remove unnecessary opening text (Preambles) ─> Move to explicit System Prompt instructions (e.g., "Give the answer directly, without introductory pleasantries")
├─ Resume interrupted output (Continuations) ──> Move to a User message ("The previous answer stopped at [...]; continue directly from there")
└─ Strong contextual reminders ──────────────> Append directly to the current User message

Platform Limitation Note: Amazon Bedrock currently does not support native Structured Outputs. If strict format enforcement is required on Bedrock, define a tool with the target parameter schema and guide the model to invoke that tool to deliver the structured payload.

Handling Tokens and Sessions: Recalculating Usage and Preserving Thinking Context

These changes may not surface in isolated simple calls, but they directly affect multi-turn dialogue systems, message history stores, billing pipelines, and long-context reliability.

1. Recounting: Roughly 30% More Tokens for the Same Input

• Mechanism Change: Haiku 5.5 adopts the updated tokenizer used by Claude 4.7 and later models. For identical input text, token counts parsed under Haiku 5.5 are approximately 30% higher than under Haiku 4.5, depending on content composition.
• Production Risks:
  1. Output Truncation: A fixed token budget holds less text. Reusing max_tokens limits tuned for Haiku 4.5 may truncate responses of equivalent length.
  2. Thinking Consuming Budget: Thinking tokens consume the same max_tokens allocation. If legacy code configured a small max_tokens, the model may exhaust its allowance during adaptive thinking, returning only thinking blocks without body text and finishing with stop_reason: "max_tokens".
  3. Billing and Estimation Drifts: Modules relying on local token counters to calculate budgets and per-call costs must be recalibrated; when calling token counting endpoints, explicitly pass model: "claude-haiku-5-5" rather than reusing legacy 4.5 estimates.

2. Preserving Prior Conversation When Passing Back Thinking Blocks

• Code to Inspect: Applications may trim earlier turns or modify system prompts and tools before feeding messages with historical thinking blocks back into the API. Haiku 4.5 did not enforce the prefix check below.
• New Strict Enforcement: Thinking blocks in Haiku 5.5 remain valid only when preceding content is preserved verbatim. If an application alters preceding system, tools, or earlier messages when passing back thinking blocks, the request returns a 400. Per documentation, accounts created before August 31, 2026, 00:00 UTC only trigger this error if the request explicitly sets thinking.block_binding.prefix_mismatch_behavior.
• Refactoring Rule: Managing conversations with thinking blocks must follow an append-only pattern. When retaining thinking blocks, never mutate preceding system prompts, tools, or message turns.

3. Replaying Sessions with the Generating Account

In multi-tenant SaaS architectures or centralized API gateways, historical sessions may reside in a central database and replay through alternate API accounts during load balancing or tenant dispatch.

• Success Status but Dropped Blocks: Thinking blocks generated by Haiku 5.5 are valid only within the originating account or linked accounts. If an unrelated Account B replays thinking blocks generated by Account A, the API does not throw an HTTP 400, but silently drops the thinking blocks.
• Consequences: The request succeeds, but the model loses access to the dropped thinking context. When storing and replaying cross-account sessions, route each dialogue to its originating account; refer to official documentation for linked-account rules.

Migrating Computer Use: Request Declarations and Execution Loops

If your implementation extends beyond conversational chat into Agent toolchains, code execution, or desktop automation, tool-layer protocol versions must be upgraded in tandem.

1. Switching to the Computer Toolset

• Applicable Platforms: Claude API direct and Google Cloud.
• Protocol Deprecation: The legacy tool name computer_20250124 and header computer-use-2025-01-24 are fully deprecated in 5.5; requests using them return HTTP 400.
• Upgrading to the New Toolset:
  1. Remove computer-use-2025-01-24 from request headers.
  2. In the tools array, declare the toolset rather than a standalone tool: {"type": "computer_toolset_20260801"}.
  3. Refactoring Dispatch Logic: Code must no longer inspect input.action alone to identify mouse and keyboard actions, but must verify both name and toolset_name on each tool_use block.
  4. Processing All Blocks and Returning Identifiers: If multiple toolset call blocks occur in a single turn, handle every block in that turn and explicitly include toolset_name when returning tool results (tool_result).
  5. Handling Default-Enabled Screen Zoom: The new toolset enables zoom by default. If your execution environment lacks zoom handling, explicitly disable it in configuration: "configs": {"zoom": {"enabled": false}}.
  6. Resolving Streaming Header Conflicts: If legacy requests include fine-grained-tool-streaming-2025-05-14, remove it. It cannot coexist with the new toolset and triggers an HTTP 400.
• New Browser Toolset: On Claude API and Google Cloud, Haiku 5.5 introduces browser_toolset_20260801 specifically tailored for web interactions, a capability not present in 4.5.

2. Replanning Priority Tier Capacity

If your team previously purchased Priority Tier throughput commitments on Claude Haiku 4.5, note that Claude Haiku 5.5 currently does not support Priority Tier. Capacity planning must be addressed separately when migrating to 5.5.

Handling Responses: Extracting Text by Block Type and Detecting Stop Reasons

After migrating to Haiku 5.5, review downstream response parsing logic on the client side.

1. Extracting Content by Block type

Many legacy implementations extracted text directly:

# Legacy approach: assume the first block contains the answer
reply_text = response.content[0].text

Because adaptive thinking is enabled by default in Haiku 5.5, the returned response.content array may begin with a thinking block of type: "thinking", with the actual answer residing in subsequent type: "text" blocks. Indexing content[0] directly risks throwing errors if that block lacks a text attribute, or dropping subsequent answer content entirely.

Updated Parsing Logic: Iterate through the content array with strict conditional branching on type. Concatenate blocks where type == "text" for user-facing responses; when type == "thinking", preserve the original block unaltered when sending it back alongside tool results.

2. Handling the refusal Stop Reason

Haiku 5.5's safety classifier can reject requests with no server-side fallback. Clients must explicitly check for this stop reason:

{ "stop_reason": "refusal" }

Add explicit handling for "refusal". If legacy code checks only "end_turn", "max_tokens", and "tool_use", encountering a refusal may hang the application workflow or crash it as an unhandled exception.

Upgrading from Haiku 3.5 or Haiku 3: Additional Checklist Items

If your production code still runs on Claude Haiku 3.5 or Haiku 3, documentation indicates that Haiku 3.5 is retired on Claude API and Amazon Bedrock, and Haiku 3 is retired on Claude API; calls to retired models fail. Google Cloud lists Haiku 3.5 as deprecated, available only to existing customers. In addition to the changes above, complete the following generational updates:

1. Model IDs and Legacy Tools:
   • Change claude-3-5-haiku-20241022, claude-3-5-haiku-latest, or claude-3-haiku-20240307 to claude-haiku-5-5; Google Cloud legacy ID claude-3-5-haiku@20241022 also changes to it, while Bedrock uses the platform-prefixed ID above.
   • The legacy Python execution tool code_execution_20250522 must be upgraded to code_execution_20250825 or newer.
   • Text editing tools must transition to text_editor_20250728 (corresponding to internal tool name str_replace_based_edit_tool); note that this version drops the undo_edit command.
2. Context Limit Exceeded Detection: In addition to catching refusal, handle model_context_window_exceeded in stop reasons.
3. Trailing Newlines in Tool Arguments: Models in the 4.5 generation and later retain trailing newlines \n in string tool arguments. If backend logic uses strict equality matching on tool arguments, permit trailing newlines.
4. Prompt Refactoring: Models in the Claude 4 generation and later adopt a more concise, direct style, benefiting from more explicit and targeted system instructions.

Comparing Request Examples and Verifying Response Parsing

The following examples illustrate migration logic based on official specifications (intended to show parameter structure changes, not live SDK execution outputs).

1. Request Comparison: Before and After

Legacy request fixing thinking budget via budget_tokens:

{
  "model": "claude-haiku-4-5",
  "max_tokens": 16000,
  "thinking": { "type": "enabled", "budget_tokens": 8000 },
  "messages": [{ "role": "user", "content": "..." }]
}

After migration, update model ID to claude-haiku-5-5, set thinking mode to adaptive, and regulate investment via output_config.effort:

{
  "model": "claude-haiku-5-5",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

This retains the documentation example's max_tokens; production implementations must recount tokens and check for truncation per task. When thinking summaries are required, add display: "summarized".

2. Python Client Response Handling Example

# Parsing example based on the official migration rules (for illustration)
from anthropic import Anthropic

client = Anthropic()

response = client.messages.create(
    model="claude-haiku-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=[
        {"role": "user", "content": "Evaluate the feasibility of this plan and provide three recommendations."}
    ]
)

# 1. Error handling: detect safety refusals
if response.stop_reason == "refusal":
    print("The safety classifier rejected the request; no answer was generated.")
elif response.stop_reason == "max_tokens":
    print("Warning: output was truncated at the Token budget limit (thinking may have used too much, or the limit may be too low).")

# 2. Extract only the current answer; preserve original thinking blocks when returning them in a tool loop
thinking_process = []
final_answers = []

for block in response.content:
    if block.type == "thinking":
        # In default mode, block.thinking is an empty string; only signature is retained
        # With display: "summarized", it contains summary text
        if hasattr(block, "thinking") and block.thinking:
            thinking_process.append(block.thinking)
    elif block.type == "text":
        final_answers.append(block.text)

print("Final answer:")
print("\n".join(final_answers))

Upgrade Verification Checklist

Review changes across requests, responses, sessions, and tools. Unused features may be skipped; before deploying to production, verify post-migration results using existing production tasks.

Request Configuration

• Model ID: Switch model IDs across your target platform; verify environment variables and gateway routing rules.
• Sampling Parameters: Remove temperature, top_p, and top_k.
• Reasoning Effort: Stop sending budget_tokens; use adaptive thinking and adjust reasoning investment with effort.
• Message Endings: Remove assistant message prefilling; enforce strict schemas via Structured Outputs or tools, moving continuations and reminders to user messages.

Responses and Token Budgets

• Body Extraction: Extract answers where type == "text"; do not rely on static indexing via content[0].
• Stop Reasons: Add handling for refusal; confirm truncation detection when hitting max_tokens.
• Output Allowance: Recalculate token allowances, adjusting max_tokens or lowering effort per task to ensure allocations are not exhausted before text generation.
• Thinking Summaries: If displaying summaries, explicitly configure display: "summarized".

Multi-turn Sessions

• Preserving Context: When sending back thinking blocks, keep preceding system prompts, tools, and message history unchanged. See legacy account compatibility above.
• Account Association: Route conversations to the account that generated the thinking blocks or linked accounts, avoiding unlinked accounts.

Tool Execution

• Computer Use: Migrate to the new toolset, remove legacy Beta headers, and verify zoom handling.
• Execution Loop: Process all tool blocks within the same turn, dispatch by name, and retain toolset identifiers when returning results.

Users migrating from Haiku 3.5 or Haiku 3 must also complete the generational additions above; teams with existing Priority Tier commitments must arrange capacity planning separately.