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. But a few defaults moved underneath you, one previously valid request combination now returns a hard 400, and one feature enterprise teams pay for is gone 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, $25 per million output tokens), so this is rarely a budget decision. It is a correctness decision. Below is every difference that can break a working integration, ordered by how likely it is to bite you on day one, with before and after snippets you can paste into your client. Anthropic’s own Opus 4.8 to Opus 5 migration guide is the primary source for the API surface. To test each change against the live endpoint first, save one request in Apidog and clone it per variant.

The short version

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

This is the change that breaks quiet, working code.

On Opus 4.8, a request with no thinking field ran without thinking. On Opus 5, that same request runs adaptive thinking. Your JSON did not change, but the model now spends tokens reasoning before it writes the visible answer. And max_tokens remains a hard cap on thinking tokens plus response tokens together, so a request that comfortably fit a 1,024-token budget on 4.8 can now burn most of that budget on thinking and return a truncated answer.

Here is the shape of a request that used to be safe:

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

Change the model ID and nothing else, and you have a truncation risk. The fix is to give the budget room:

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

Two things to check after you raise the ceiling. Watch stop_reason in the response: max_tokens means you got cut off, end_turn means the model finished. Then read the usage block to see how much of the budget thinking actually consumed on your real prompts, and size the number from measurement rather than a guess.

If you genuinely want the old no-thinking behavior, send thinking: {"type": "disabled"} explicitly. Read the next section first, because that field now interacts with effort in a way that returns an error.

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

This is the trap most likely to show up in your error logs, because both halves of it were valid separately on Opus 4.8.

On Opus 5, thinking: {"type": "disabled"} combined with output_config.effort set to xhigh or max returns an HTTP 400. Anthropic enforces it per request, so it fails immediately and consistently rather than degrading. The logic is straightforward: the top two effort levels exist to buy more thinking, so asking for maximum effort with thinking switched off is a contradiction.

The request that 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 the capability. Drop the thinking field, keep the high effort. This is Anthropic’s recommended direction, and it is the one to pick for coding and agentic work:

{
  "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 off. For a latency-sensitive path that truly needs no thinking, keep disabled and pull effort down to 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."}
  ]
}

One caution on Fix B. Anthropic documents two artifacts that appear occasionally with thinking disabled: tool calls written out as plain text instead of being executed, and internal XML tags such as <thinking> leaking into visible output. In an agentic loop the leaked text also poisons later turns. Anthropic’s own mitigation is to keep thinking on and control cost with a lower effort level instead. Treat Fix B as the narrow option, not the default.

3. Effort levels were recalibrated, so re-sweep instead of copying settings

Opus 5 defaults to high effort, and the levels themselves were recalibrated. low and medium are meaningfully stronger on Opus 5 than on earlier Opus models, so a setting you tuned on 4.8 no longer lands on the same cost and quality point. Anthropic says plainly to run a fresh effort sweep rather than carrying your 4.8 configuration over, and that advice cuts both ways:

• Workloads pinned to high or xhigh on 4.8 for quality may hold up at medium on Opus 5, which is a real bill reduction at identical per-token pricing.
• Workloads pinned to low for cost may be worth pushing up a level, because quality per token improved.

For coding and long-horizon agentic work, xhigh remains the recommended starting point. Pair it with a generous max_tokens (64k is a sensible starting budget at the top levels) so thinking has somewhere to go.

Run the sweep on your own evaluation set, not on a benchmark. Fix the prompt, vary only the effort value, and record output quality, latency, and usage for each level. The effort parameter deep dive covers the mechanics of each level; for the cost side of the same decision, see the Opus 5 pricing breakdown.

4. Remove the long-context beta header

Opus 5 ships with a 1M-token context window as both the default and the maximum. There is no beta header to enable it and no long-context pricing premium attached.

If your client still sends the extended-context beta value in the anthropic-beta header from your Opus 4.8 setup, it is dead weight now. Strip it out. Stale beta values in a shared HTTP client are how you end up debugging an unrelated request six months later.

Max output on the Messages API is 128k tokens. If you need more, the Batch API goes to 300k output tokens with the output-300k-2026-03-24 beta header, a separate opt-in from anything you were doing for context length.

5. The prompt cache minimum drops to 512 tokens

On Opus 4.8, a prompt segment had to reach 1,024 tokens to be eligible for caching. On Opus 5 the floor is 512. Nothing in your code has to change, and cache reads at $0.50 per million are the cheapest tokens on the price sheet against $5 base input.

What is worth doing is a review pass. Look for system prompts, tool definitions, and few-shot blocks that sat between 512 and 1,024 tokens and were never worth a cache_control breakpoint before. They are worth one now. Confirm the effect by reading cache_read_input_tokens in the response usage block: on the second identical call it should be non-zero. Our guide to cutting a Claude API bill covers the broader caching strategy.

6. Mid-conversation system messages are now accepted

Opus 4.8 rejected a {"role": "system"} entry inside the messages array with a 400. Opus 5 accepts it. This is additive, so it breaks nothing, but it can delete a workaround. If you built machinery that folds mid-conversation instruction changes into a synthetic user turn, you can now put the instruction inline where it belongs:

{
  "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 is a per-model capability. If you route the same conversation history to Opus 4.8 as a fallback, the older model will still 400 on that message.

7. Priority Tier is not supported on Opus 5

This one stings for enterprise teams, and it is easy to miss because it is an absence rather than an error you can grep for. Opus 4.8 supports Priority Tier. Opus 5 does not. If you bought committed throughput to guarantee latency on a production path, migrating that path moves it back to standard capacity.

There is no clever fix. Either keep latency-critical traffic on claude-opus-4-8 while everything else moves to Opus 5, or accept standard capacity and measure whether your tail latency actually degrades. Split the migration by workload rather than flipping the whole fleet at once.

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

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 it delivers roughly 2.5x output speed at $10 per million input and $50 per million output. It is a research preview, first-party API only (not Amazon Bedrock, Google Cloud, or Microsoft Foundry), and it does not combine with the Batch API. Reach for it on interactive paths, not background jobs.

Server-side fallback for cyber refusals. Sending fallbacks: "default" with the server-side-fallback-2026-07-01 beta header makes a request that Opus 5 refuses on cyber-category grounds fall back to Opus 4.8 automatically. Security tooling is where this earns its keep.

There is also a mid-conversation-tool-changes-2026-07-01 beta header that lets you add or remove tool definitions between turns without invalidating the prompt cache: a cost lever for long agent sessions with a changing toolset.

9. What did not change

It saves time to know what you can leave alone:

• Sampling parameters still return a 400. temperature, top_p, and top_k at non-default values are rejected, same as on Opus 4.8. Steer behavior through the system prompt.
• Token counts are roughly the same. Opus 5 uses the same tokenizer family as 4.8, so existing token budgets and cost models carry over without a recount. That is the opposite of the Sonnet 4.6 to Sonnet 5 move, which shifted counts by about 30%.
• Base pricing is identical. $5 in, $25 out, matching Opus 4.8, 4.7, 4.6, and 4.5. See the Opus 4.8 pricing page.
• Request and response shape. Streaming, tool use, vision, structured outputs, and batch all work the way they did.

One thing changed even where the API did not: Opus 5 verifies its own work unprompted, so carried-over “double-check your answer” instructions cause over-verification and waste tokens. Default responses also run longer than 4.8’s, and lowering effort cuts thinking rather than visible length, so ask for brevity explicitly. Those are prompt-level fixes, covered in prompting Claude Opus 5.

Verify the migration before you ship it

Every item above is an HTTP-level difference, which makes it testable outside your application. A workable loop in Apidog:

1. Save one request to the Messages endpoint with your key stored as an environment variable, never inline in the body.
2. Clone it into variants: claude-opus-4-8 baseline, claude-opus-5 with defaults, and one clone per effort level.
3. Fire the disabled-thinking plus xhigh combination deliberately and record the 400 body, so you recognize it in production logs.
4. Assert on stop_reason so a truncated max_tokens response fails your test instead of quietly shipping.
5. Send an identical cached request twice and check usage.cache_read_input_tokens on the second call.
6. Run one streaming request and confirm your SSE parser handles the thinking blocks that now arrive by default.

Download Apidog to keep that as a reusable collection for every future model swap.

One honest caveat before you migrate 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 says so itself in the launch post. The launch benchmark claims (Frontier-Bench, ARC-AGI 3, OSWorld 2.0, CursorBench 3.2) are vendor-run and not independently reproduced as of July 25, 2026. Treat them as Anthropic’s reported numbers and run your own evals before committing a production workload. The accurate summary: frontier-class capability at half the frontier price, with a named ceiling above it.

Migration checklist

Work through this in order:

1. Change the model string to exactly claude-opus-5. No date suffix.
2. Raise max_tokens on every request that previously omitted thinking. Thinking now runs by default and shares that budget.
3. Grep your codebase for "disabled" and confirm no request pairs it with effort xhigh or max. That combination is a hard 400.
4. Remove the long-context beta value from anthropic-beta. The 1M window is the default now.
5. Re-run your effort sweep from scratch on your own evals. Do not port 4.8 settings.
6. Add cache_control breakpoints to prompt segments between 512 and 1,024 tokens.
7. Identify any traffic on Priority Tier and decide per workload whether it stays on claude-opus-4-8.
8. Delete carried-over verification instructions from your prompts, and add explicit conciseness instructions where output length matters.
9. Optionally enable fallbacks: "default" if your workload triggers cyber-category refusals.
10. Assert on stop_reason in your test suite so truncation surfaces as a failure, not a subtly worse answer.

For the full request walkthrough, see the Claude Opus 5 API guide, or start with what Claude Opus 5 is for specs and availability. If you still run the older model in places, the Opus 4.8 explainer and its API walkthrough remain accurate for it. Anthropic’s models overview is the source of record for IDs, context windows, and cutoffs.

FAQ

Is Opus 4.8 to Opus 5 a drop-in migration? Close, but not quite. Changing the model string works for most requests. Two things can break: thinking now runs by default and shares your max_tokens budget, and thinking: {"type": "disabled"} with effort xhigh or max returns a 400. Priority Tier traffic also needs a decision, since Opus 5 does not support it.

Why am I getting a 400 after switching to claude-opus-5? The most common cause is disabling thinking while requesting xhigh or max effort. Either remove the thinking field and keep the high effort, or keep thinking disabled and drop effort to high or lower. Non-default temperature, top_p, or top_k values also still return a 400, exactly as on Opus 4.8.

Do I need to recount my tokens after migrating? No. Opus 5 uses the same tokenizer family as Opus 4.8, so 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 identical too, at $5 in and $25 out, though your bill can still move if thinking-by-default increases output tokens.