refusals-and-fallback changedbuild-with-claude/refusals-and-fallback
Recorded here
Lines+5added
Lines−4removed
From line
15
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits35to this page, all time
The whole hunk
from line 15, old and new numbered
/
from line 15
1515 - claude-haiku-5-5
1616 supportedPlatforms:
1717 Claude API: stable
18 Amazon Bedrock: stable
19 Amazon Bedrock (bedrock-runtime): stable
1820 Claude Platform on AWS: stable
1921 Claude Models on Google Cloud (Anthropic managed): stable
20 Amazon Bedrock: stable
2122 Claude Models on Google Cloud (Google managed): stable
2223 Microsoft Foundry: stable
2324---
from line 781
780781
781782<CodeGroup exclude="shell">
782783 <CodeGroupItem language="cURL">
783 The refusal-fallback middleware is part of the Claude SDK, so a cURL request can’t use it. To fall back within a single request, use [server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback). To write the retry yourself, see [Fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit).
784 The refusal-fallback middleware is part of the Anthropic SDK, so a cURL request can’t use it. To fall back within a single request, use [server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback). To write the retry yourself, see [Fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit).
784785 </CodeGroupItem>
785786
786787 <CodeGroupItem language="CLI">
from line 1126
11251126
11261127* Retries walk your fallback list in order. A fallback model that itself refuses passes the request to the next entry.
11271128* When every model in the list has declined, the middleware returns the final refusal (the last model’s refusal response) rather than raising an error.
1128* Thinking blocks from Claude Fable 5.2, Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5, or Claude Fable 5 pass through unchanged. Each retry re-sends your original request body, and the only blocks the middleware removes from conversation history on later requests are the `fallback` boundary blocks it added itself. Apart from Claude Mythos 5.2, no other model reads Claude Fable 5.2 blocks. Only Claude Fable 5.1, Claude Mythos 5.1, and, on the Claude API, Claude Fable 5.2 and Claude Mythos 5.2 [read Claude Fable 5.1 blocks](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models). The API drops any Claude Fable 5.2 or Claude Fable 5.1 block that the fallback model can’t read. The API also drops any Claude Opus 5.5 or Claude Sonnet 5.5 block that the fallback model can’t read (see [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models)). Claude Opus 5.5 and Claude Sonnet 5.5 read Claude Haiku 5.5 blocks on the Claude API and Claude Models on Google Cloud (Google managed), as do Claude Fable 5.2 and Claude Mythos 5.2 on the Claude API, and the API drops them for a fallback model that can’t read them. On Claude Models on Google Cloud (Google managed), Claude Fable 5.2 and Claude Mythos 5.2 read the same blocks as on the Claude API.
1129* Thinking blocks from Claude Fable 5.2, Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5, or Claude Fable 5 pass through unchanged. Each retry re-sends your original request body, and the only blocks the middleware removes from conversation history on later requests are the `fallback` boundary blocks it added itself. Apart from Claude Mythos 5.2, no other model reads Claude Fable 5.2 blocks. Claude Fable 5.1 and Claude Mythos 5.1 [read Claude Fable 5.1 blocks](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models), and so do Claude Fable 5.2 and Claude Mythos 5.2 on the Claude API and Claude Models on Google Cloud (Google managed). No other model reads them. The API drops any Claude Fable 5.2 or Claude Fable 5.1 block that the fallback model can’t read. The API also drops any Claude Opus 5.5 or Claude Sonnet 5.5 block that the fallback model can’t read (see [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models)). On the Claude API and Claude Models on Google Cloud (Google managed), Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.2, and Claude Mythos 5.2 read Claude Haiku 5.5 blocks. The API drops them for a fallback model that can’t read them.
11291130* Responses served through the middleware include a `fallback` content block at each model boundary, the same as server-side fallback responses. The middleware manages those blocks for you on later requests.
11301131* The model that accepted is recorded in `BetaFallbackState` (go: `betafallback.BetaFallbackState`), so follow-up requests that share the state stay pinned to it rather than re-asking a model that refused.
11311132
from line 1146
11451146 <Step title="Re-send on a fallback model">
11461147 Send the same request with `model` set to a fallback model, such as Claude Opus 4.8. If the refused request sent `thinking: {"type": "between_tools"}`, change `thinking` first: only Claude Sonnet 5.5 accepts that value, so omit `thinking` or set a value the fallback model accepts. [Server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback) under the `2026-07-01` header makes this change for you when it falls back to Claude Sonnet 5. Another model can normally serve a request that Claude Fable 5.2, Claude Fable 5.1, or Claude Fable 5 declines. How you handle the conversation history depends on whether you redeem a [fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit):
11471148
1148 * **Not redeeming a credit:** you can leave the earlier `thinking` and `redacted_thinking` blocks in place or strip them to save input tokens. The fallback model normally can’t use them either way. Apart from Claude Mythos 5.2, no other model reads Claude Fable 5.2 blocks. Only Claude Fable 5.1, Claude Mythos 5.1, and, on the Claude API, Claude Fable 5.2 and Claude Mythos 5.2 [read Claude Fable 5.1 blocks](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models). Only those four models, Claude Fable 5, and Claude Mythos 5 read Claude Fable 5 blocks. The API drops any of these blocks that the fallback model can’t read. It also drops any Claude Opus 5.5 or Claude Sonnet 5.5 block that the fallback model can’t read (see [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models)). A retry after a Claude Haiku 5.5 refusal is always in this case. Claude Opus 5.5 and Claude Sonnet 5.5 read Claude Haiku 5.5 blocks on the Claude API and Claude Models on Google Cloud (Google managed), as do Claude Fable 5.2 and Claude Mythos 5.2 on the Claude API, so leave those blocks in place when you fall back to one of those models there. For a fallback model that can’t read them, the API drops them without billing them. On Claude Models on Google Cloud (Google managed), Claude Fable 5.2 and Claude Mythos 5.2 read the same blocks as on the Claude API.
1149 * **Not redeeming a credit:** you can leave the earlier `thinking` and `redacted_thinking` blocks in place or strip them to save input tokens. The fallback model normally can’t use them either way. Apart from Claude Mythos 5.2, no other model reads Claude Fable 5.2 blocks. Claude Fable 5.1 and Claude Mythos 5.1 [read Claude Fable 5.1 blocks](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models), and so do Claude Fable 5.2 and Claude Mythos 5.2 on the Claude API and Claude Models on Google Cloud (Google managed). No other model reads them. Only those four models, Claude Fable 5, and Claude Mythos 5 read Claude Fable 5 blocks. The API drops any of these blocks that the fallback model can’t read. It also drops any Claude Opus 5.5 or Claude Sonnet 5.5 block that the fallback model can’t read (see [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models)). A retry after a Claude Haiku 5.5 refusal is always in this case. On the Claude API and Claude Models on Google Cloud (Google managed), Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.2, and Claude Mythos 5.2 read Claude Haiku 5.5 blocks, so leave those blocks in place when you fall back to one of those models there. For a fallback model that can’t read them, the API drops them without billing them.
11491150 * **Redeeming a credit:** send the body unchanged, because redemption requires an exact match. The server handles the earlier model’s thinking blocks on a redemption, so do not strip them (see [Fields that must match the refused request](https://platform.claude.com/docs/en/build-with-claude/fallback-credit#reference)).
11501151 </Step>
11511152
No line in this hunk matches that.