Migrating from Claude Opus 4.8 to Opus 5: Every Breaking Change

Swapping claude-opus-4-8 for claude-opus-5 looks like a one-line change. It mostly is. However, several defaults changed, one previously valid request combination now returns a hard 400, and a feature used by enterprise teams is not available on the new model. Anthropic shipped Claude Opus 5 on July 24, 2026 at the same price as Opus 4.8 ($5 per million input tokens and $25 per million output tokens), so this is primarily a correctness migration. Anthropic’s Opus 4.8 to Opus 5 migration guide is the source for the API changes. To test each variation against the live endpoint, save a request in Apidog and clone it per configuration.

Try Apidog today

The short version

Change	Impact	Action
Thinking is on by default	Silent output truncation	Raise max_tokens
thinking: disabled + effort xhigh/max	HTTP 400	Pick one or the other
Effort levels recalibrated	Wrong cost/quality point	Re-sweep; do not carry settings over
1M context needs no beta header	Header is redundant	Remove it
Cache minimum drops to 512 tokens	Lower-cost cache opportunities	Cache more prompt segments
Mid-conversation system messages	Previously a 400, now accepted	Optionally simplify conversation handling
Priority Tier	Not supported on Opus 5	Keep 4.8 for that traffic
Fast mode	Available on Opus 5	Optional, $10/$50
fallbacks: "default"	Cyber-refusal fallback	Optional beta header
Sampling parameters, token counts	Unchanged	No migration needed

1. Thinking is on by default, and max_tokens still caps everything

This is the most likely change to break otherwise working code.

On Opus 4.8, omitting the thinking field meant the request ran without thinking. On Opus 5, the same request uses adaptive thinking. The model can spend tokens reasoning before producing visible output.

max_tokens is still a hard shared limit for thinking tokens and response tokens. A request that fit within a 1,024-token budget on Opus 4.8 can now spend most of that budget on thinking and return a truncated answer.

A previously safe request:

{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Summarize this incident report in three bullets."
    }
  ]
}

After changing only the model ID, raise the budget:

{
  "model": "claude-opus-5",
  "max_tokens": 8192,
  "messages": [
    {
      "role": "user",
      "content": "Summarize this incident report in three bullets."
    }
  ]
}

Validate the change with two response fields:

1. Check stop_reason.
   • max_tokens means the response was cut off.
   • end_turn means the model completed its answer.
2. Inspect usage to measure how many tokens thinking consumes on real prompts.

Size the budget from production-like measurements rather than guessing.

If you need the old no-thinking behavior, set it explicitly:

{
  "thinking": {
    "type": "disabled"
  }
}

Read the next section before doing that: disabled thinking now conflicts with the highest effort levels.

2. The 400: disabled thinking plus xhigh or max effort

On Opus 5, this combination returns HTTP 400:

• thinking: {"type": "disabled"}
• output_config.effort: "xhigh" or "max"

Both options were individually valid on Opus 4.8. On Opus 5, Anthropic rejects the combination per request because the top effort levels are intended to buy more thinking.

This request now fails:

{
  "model": "claude-opus-5",
  "max_tokens": 8192,
  "thinking": {
    "type": "disabled"
  },
  "output_config": {
    "effort": "xhigh"
  },
  "messages": [
    {
      "role": "user",
      "content": "Refactor this module and explain the tradeoffs."
    }
  ]
}

Fix A: Keep high effort and enable thinking

For coding and agentic work, remove the thinking field and keep high effort:

{
  "model": "claude-opus-5",
  "max_tokens": 32000,
  "output_config": {
    "effort": "xhigh"
  },
  "messages": [
    {
      "role": "user",
      "content": "Refactor this module and explain the tradeoffs."
    }
  ]
}

Fix B: Keep thinking disabled and lower effort

For latency-sensitive routes that must avoid thinking, keep disabled but use high or lower:

{
  "model": "claude-opus-5",
  "max_tokens": 4096,
  "thinking": {
    "type": "disabled"
  },
  "output_config": {
    "effort": "high"
  },
  "messages": [
    {
      "role": "user",
      "content": "Classify this ticket into one of five categories."
    }
  ]
}

Use Fix B narrowly. Anthropic documents occasional artifacts with thinking disabled:

• Tool calls may be emitted as plain text instead of executed.
• Internal XML such as <thinking> can appear in visible output.
• In agent loops, leaked text can affect later turns.

For most workloads, keep thinking enabled and manage cost through a lower effort level.

3. Re-sweep effort levels instead of copying Opus 4.8 settings

Opus 5 defaults to high effort, and effort levels were recalibrated.

low and medium are meaningfully stronger on Opus 5 than on earlier Opus models. A setting tuned for Opus 4.8 no longer maps to the same cost, latency, or quality profile.

Run a fresh effort sweep on your own evaluation set:

1. Keep the prompt and test cases fixed.
2. Run each request at low, medium, high, xhigh, and max where applicable.
3. Record output quality, latency, and usage.
4. Choose the lowest effort level that meets your quality target.

This can work in both directions:

• Workloads using high or xhigh on Opus 4.8 may perform adequately at medium on Opus 5.
• Workloads pinned to low for cost may justify moving up a level because quality per token improved.

For coding and long-horizon agentic workloads, xhigh remains the recommended starting point. Pair it with a generous max_tokens value. At the top effort levels, 64k is a sensible starting budget so thinking has room to run.

See the effort parameter deep dive for effort mechanics and the Opus 5 pricing breakdown for cost considerations.

4. Remove the long-context beta header

Opus 5 has a 1M-token context window by default, and 1M tokens is also the maximum context size.

You no longer need a beta header to enable long context. There is no long-context pricing premium attached.

Remove any extended-context beta value from your shared anthropic-beta header configuration. Keeping stale beta headers creates unnecessary debugging risk later.

The Messages API supports up to 128k output tokens. If you need more output, the Batch API supports up to 300k output tokens with this separate beta header:

anthropic-beta: output-300k-2026-03-24

That opt-in is unrelated to context length.

5. The prompt cache minimum drops to 512 tokens

On Opus 4.8, a prompt segment needed at least 1,024 tokens to be eligible for caching. On Opus 5, the minimum is 512 tokens.

No code change is required for existing cache breakpoints. However, review prompt segments that are between 512 and 1,024 tokens:

• System prompts
• Tool definitions
• Few-shot examples
• Reused policy or formatting blocks

These blocks may now be worth caching with cache_control.

Confirm caching by checking this field in the response usage object:

{
  "cache_read_input_tokens": 0
}

On the second identical request, cache_read_input_tokens should be non-zero when the cache is used. Cache reads cost $0.50 per million tokens, compared with $5 per million base input tokens.

For a broader strategy, see the guide to cutting a Claude API bill.

6. Mid-conversation system messages are now accepted

Opus 4.8 rejected {"role": "system"} inside the messages array with HTTP 400. Opus 5 accepts it.

This is additive: existing requests continue to work, but you can remove workarounds that encoded mid-conversation instruction changes as synthetic user messages.

{
  "model": "claude-opus-5",
  "max_tokens": 8192,
  "messages": [
    {
      "role": "user",
      "content": "Draft the release note."
    },
    {
      "role": "assistant",
      "content": "Here is a first draft..."
    },
    {
      "role": "system",
      "content": "From here on, keep responses under 150 words."
    },
    {
      "role": "user",
      "content": "Tighten it."
    }
  ]
}

This capability is model-specific. If the same conversation can fall back to Opus 4.8, normalize or remove mid-conversation system messages before sending the request to that model.

7. Priority Tier is not supported on Opus 5

Opus 4.8 supports Priority Tier. Opus 5 does not.

If you use committed throughput to guarantee latency on a production route, moving that route to Opus 5 moves it back to standard capacity.

Handle this per workload:

• Keep latency-critical traffic on claude-opus-4-8.
• Move non-critical workloads to Opus 5.
• Measure tail latency before migrating a production path that depends on Priority Tier.

Do not flip the entire fleet at once if throughput guarantees matter.

8. Fast mode works, and there is a cyber-refusal fallback

Fast mode

Fast mode runs on Opus 5. It returned an error on Opus 4.7 and silently ran at standard speed on Opus 4.6.

On Opus 5, Fast mode provides roughly 2.5x output speed at:

• $10 per million input tokens
• $50 per million output tokens

It is a research preview and is available through the first-party API only, not Amazon Bedrock, Google Cloud, or Microsoft Foundry. It also cannot be combined with the Batch API.

Use it for interactive user-facing paths, not background jobs.

Server-side fallback for cyber refusals

You can enable automatic fallback to Opus 4.8 when Opus 5 refuses a cyber-category request.

Send:

{
  "fallbacks": "default"
}

Along with:

anthropic-beta: server-side-fallback-2026-07-01

This is especially relevant for security tooling.

There is also a beta header for changing tool definitions during a conversation without invalidating the prompt cache:

anthropic-beta: mid-conversation-tool-changes-2026-07-01

Use it for long-running agent sessions with a changing toolset.

9. What did not change

You can leave these parts of an Opus 4.8 integration alone:

• Sampling parameters still return 400. Non-default temperature, top_p, and top_k values are rejected, as they were on Opus 4.8. Use prompts to steer behavior.
• Token counts are roughly the same. Opus 5 uses the same tokenizer family as 4.8, so existing token budgets and cost models do not need a recount.
• Base pricing is identical. Input remains $5 per million tokens and output remains $25 per million tokens. See the Opus 4.8 pricing page.
• Request and response shapes remain compatible. Streaming, tool use, vision, structured outputs, and batch requests work as before.

One behavior changed even where the API did not: Opus 5 verifies its own work without being prompted. Remove carried-over instructions such as “double-check your answer,” which can cause over-verification and waste tokens.

Opus 5 responses also tend to run longer than Opus 4.8 responses. Lowering effort reduces thinking, not necessarily visible answer length. When output length matters, instruct the model explicitly:

Answer in no more than 150 words. Use three bullets. Do not include reasoning.

See prompting Claude Opus 5 for prompt-level guidance.

Verify the migration before shipping

Each difference above is testable at the HTTP layer. Use this workflow in Apidog:

1. Save one request to the Messages endpoint. Store the API key in an environment variable, not inline in the request body.
2. Clone it into variants:
   • claude-opus-4-8 baseline
   • claude-opus-5 with defaults
   • One clone per effort level
3. Send a request with disabled thinking and xhigh effort. Save the 400 response body so you can identify it in production logs.
4. Assert that stop_reason is not max_tokens.
5. Send an identical cached request twice and check usage.cache_read_input_tokens on the second response.
6. Run a streaming request and confirm your SSE parser supports the thinking blocks that now arrive by default.

Download Apidog and keep these requests as a reusable collection for future model migrations.

One caveat before migrating everything

Opus 5 is not the top of the Claude stack. Fable 5 remains Anthropic’s most capable widely released model, and Opus 5 still trails Mythos 5 on cybersecurity exploitation and autonomous biology research.

Anthropic states this in its launch post. Its launch benchmark claims—including Frontier-Bench, ARC-AGI 3, OSWorld 2.0, and CursorBench 3.2—are vendor-run and had not been independently reproduced as of July 25, 2026.

Treat those results as Anthropic-reported numbers. Run your own evaluation suite before committing a production workload.

Migration checklist

Work through these items in order:

1. Change the model ID to exactly claude-opus-5. Do not add a date suffix.
2. Raise max_tokens for every request that previously omitted thinking.
3. Search the codebase for "disabled" and ensure no request combines it with xhigh or max effort.
4. Remove the long-context beta value from anthropic-beta.
5. Re-run your effort sweep on your own evaluations. Do not port Opus 4.8 effort settings directly.
6. Add cache_control breakpoints to reusable prompt segments between 512 and 1,024 tokens.
7. Identify Priority Tier traffic and decide whether each workload should remain on claude-opus-4-8.
8. Remove inherited verification instructions and add explicit brevity constraints where needed.
9. Optionally enable fallbacks: "default" for workloads that trigger cyber-category refusals.
10. Add a test assertion that fails when stop_reason equals max_tokens.

For a full request walkthrough, see the Claude Opus 5 API guide. For specifications and availability, start with what Claude Opus 5 is.

If you still use the older model, the Opus 4.8 explainer and Opus 4.8 API walkthrough remain accurate for it. Anthropic’s models overview is the source of record for model IDs, context windows, and cutoffs.

FAQ

Is Opus 4.8 to Opus 5 a drop-in migration?

Almost. Changing the model string works for most requests, but thinking now runs by default and shares the max_tokens budget. Also, thinking: {"type": "disabled"} combined with xhigh or max effort returns HTTP 400. Priority Tier traffic needs a separate migration decision because Opus 5 does not support it.

Why am I getting a 400 after switching to claude-opus-5?

The most common cause is disabled thinking with xhigh or max effort. Either remove the thinking field and keep high effort, or keep thinking disabled and lower effort to high or below.

Non-default temperature, top_p, and top_k values also still return 400, exactly as they did on Opus 4.8.

Do I need to recount tokens after migrating?

No. Opus 5 uses the same tokenizer family as Opus 4.8, so token counts are roughly unchanged and existing budgets carry over. Tool-use system prompt overhead is slightly lower at 286 tokens versus 290.

Base pricing is also unchanged at $5 per million input tokens and $25 per million output tokens. Your total bill can still change if thinking-by-default increases output token usage.