SPB Git

Repository Public

refusals-and-fallback.md 56.2 KB 1,180 lines markdown

1---2title: Refusals and fallback3url: https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback4description: How Claude Fable and Claude Opus models return classifier refusals and how to retry refused requests on a fallback model.5---67Claude Fable 5.1, Claude Fable 5, and Claude Opus 5 include safety classifiers that can decline a request. When that happens, you receive a normal response, not an error, with `stop_reason: "refusal"`. Its `stop_details.category` names the policy area (see [What a refusal looks like](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response)). You can usually still get an answer by sending the same request to another Claude model. This page shows you how to recognize a refusal and how to set up that retry.89Read this page when you build on any of these models and want declined requests to fall through to another model automatically. It also applies when you have seen `"refusal"` in a response and want to know what to do next.1011Related pages:1213* [Stop reasons and fallback](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons): the full list of `stop_reason` values.14* [Fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit): how to avoid paying the prompt-cache cost twice when you build the retry yourself.15* [SDK middleware](https://platform.claude.com/docs/en/cli-sdks-libraries/middleware): the SDK helper that wraps all of this.16* [Fallback and billing cookbook](https://platform.claude.com/cookbook/fable-5-fallback-billing-guide): a worked end-to-end example.1718The simplest setup, in beta on the Claude API: set `fallbacks` to `"default"`, and the API retries a declined request on the fallback model Anthropic recommends for its refusal category. For categories with no recommended fallback, the refusal stands.1920<CodeGroup>21  ```bash cURL22  curl --fail-with-body -sS https://api.anthropic.com/v1/messages \23    -H "x-api-key: $ANTHROPIC_API_KEY" \24    -H "anthropic-version: 2023-06-01" \25    -H "anthropic-beta: server-side-fallback-2026-07-01" \26    -H "content-type: application/json" \27    -d '{28      "model": "claude-fable-5",29      "max_tokens": 1024,30      "fallbacks": "default",31      "messages": [{"role": "user", "content": "Hello, Claude"}]32    }'33  ```3435  ```bash CLI36  ant beta:messages create \37    --model claude-fable-5 \38    --max-tokens 1024 \39    --message '{"role":"user","content":"Hello, Claude"}' \40    --fallbacks default \41    --beta server-side-fallback-2026-07-0142  ```4344  ```python Python45  client = Anthropic()4647  response = client.beta.messages.create(48      model="claude-fable-5",49      max_tokens=1024,50      messages=[{"role": "user", "content": "Hello, Claude"}],51      fallbacks="default",52      betas=["server-side-fallback-2026-07-01"],53  )54  print(response.model)55  ```5657  ```typescript TypeScript58  const client = new Anthropic();5960  const response = await client.beta.messages.create({61    model: "claude-fable-5",62    max_tokens: 1024,63    messages: [{ role: "user", content: "Hello, Claude" }],64    fallbacks: "default",65    betas: ["server-side-fallback-2026-07-01"]66  });67  console.log(response.model);68  ```6970  ```csharp C#71  AnthropicClient client = new();7273  BetaMessage response = await client.Beta.Messages.Create(74      new()75      {76          Model = Messages::Model.ClaudeFable5,77          MaxTokens = 1024,78          Messages = [new() { Content = "Hello, Claude", Role = Role.User }],79          Fallbacks = new Default(),80          Betas = [AnthropicBeta.ServerSideFallback2026_07_01],81      }82  );8384  Console.WriteLine(response.Model.Raw());85  ```8687  ```go Go88  client := anthropic.NewClient()8990  response, err := client.Beta.Messages.New(context.Background(), anthropic.BetaMessageNewParams{91  	Model:     anthropic.ModelClaudeFable5,92  	MaxTokens: 1024,93  	Messages: []anthropic.BetaMessageParam{94  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude")),95  	},96  	Fallbacks: anthropic.BetaFallbacksParamOfDefault(),97  	Betas:     []anthropic.AnthropicBeta{anthropic.AnthropicBetaServerSideFallback2026_07_01},98  })99  if err != nil {100  	panic(err)101  }102103  fmt.Println(response.Model)104  ```105106  ```java Java107  AnthropicClient client = AnthropicOkHttpClient.fromEnv();108109  BetaMessage response = client.beta().messages().create(MessageCreateParams.builder()110      .model(Model.CLAUDE_FABLE_5)111      .maxTokens(1024L)112      .addUserMessage("Hello, Claude")113      .fallbacksDefault()114      .addBeta(AnthropicBeta.SERVER_SIDE_FALLBACK_2026_07_01)115      .build());116117  IO.println(response.model().asString());118  ```119120  ```php PHP121  $client = new Client();122123  $response = $client->beta->messages->create(124      model: 'claude-fable-5',125      maxTokens: 1024,126      messages: [['role' => 'user', 'content' => 'Hello, Claude']],127      fallbacks: 'default',128      betas: ['server-side-fallback-2026-07-01'],129  );130131  echo $response->model, PHP_EOL;132  ```133134  ```ruby Ruby135  client = Anthropic::Client.new136137  response = client.beta.messages.create(138    model: "claude-fable-5",139    max_tokens: 1024,140    messages: [{role: "user", content: "Hello, Claude"}],141    fallbacks: :default,142    betas: ["server-side-fallback-2026-07-01"]143  )144145  puts response.model146  ```147</CodeGroup>148149The following sections cover what a refusal response contains, when to use server-side or client-side fallback, and how each is billed.150151## What a refusal looks like152153A refusal is a successful HTTP 200 response with `stop_reason: "refusal"`:154155```json156{157  "id": "msg_01XFUDYJgAACzvnptvVoYEL",158  "type": "message",159  "role": "assistant",160  "model": "claude-fable-5",161  "content": [],162  "stop_reason": "refusal",163  "stop_details": {164    "type": "refusal",165    "category": "cyber",166    "explanation": "This request was declined because it could enable cyber harm."167  },168  "usage": {169    "input_tokens": 412,170    "output_tokens": 0171  }172}173```174175The `stop_details` object explains the decline:176177* **`category`:** names the policy area that triggered the classifier.178* **`explanation`:** a human-readable description. The text is not stable, so display it rather than parse it.179* **`recommended_model`:** present only on requests that set `fallbacks` ([server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback), beta). It names a model to retry directly when the API skipped the fallback attempt (for example, the fallback model was rate limited), and is `null` otherwise. It's a hint, not a guarantee.180* `category` and `explanation` are both `null` when the refusal does not map to a named category. That `null` is a normal, permanent value, not a placeholder.181* `stop_details` itself is `null` for every stop reason other than `refusal`.182183| `category`               | What it means                                                                                                                                                                                                                             |184| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |185| `"cyber"`                | The request could enable cyber harm, such as malware or exploit development. Benign cybersecurity work can also trigger this category.                                                                                                    |186| `"bio"`                  | The request could enable biological harm, such as dangerous lab methods. Beneficial life sciences work can also trigger this category.                                                                                                    |187| `"frontier_llm"`         | The request could assist the development of competing AI models, which is restricted under [Anthropic's commercial terms](https://www.anthropic.com/legal/commercial-terms). Benign machine learning work can also trigger this category. |188| `"reasoning_extraction"` | The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking).              |189| `"general_harms"`        | The request falls under a usage-policy area outside the four named categories. Benign work can also trigger this category.                                                                                                                |190191A refusal can arrive before any output, or mid-stream after partial output. In either case, treat any partial output as incomplete and discard it.192193<Note>194  **How refusals are billed:** You are not billed for a refusal that arrives before any output. `content` is empty, and token counts appear in `usage` but are not charged. The request still counts against your rate limits. A mid-stream refusal bills the input tokens and the output already streamed at normal rates.195</Note>196197## Picking a fallback approach198199There are three ways to retry a refused request on another model. The right one depends on where you are running and how much control you need.200201| Your situation                       | Use                                                                                                                                                                                                      | Why                                                         |202| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |203| Claude API, simplest setup           | [Server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback)                                                                                 | One request, one response. The API handles the retry.       |204| Any platform, using an Anthropic SDK | [The SDK middleware](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#client-side-fallback)                                                                                   | Configure once on the client. Retries happen automatically. |205| Raw HTTP or custom retry logic       | [A manual retry](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#manual-retry) with [fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit) | Full control. Fallback credit keeps the cost down.          |206207Server-side fallback and the SDK middleware apply fallback credit for you. You only need the [Fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit) page when you build the retry yourself.208209## Server-side fallback210211Server-side fallback retries a refused request inside a single API call. In the default mode, when the primary model declines and the refusal category has a recommended fallback, the API runs the same request on the model Anthropic recommends for that category. You can instead [name up to three fallback models of your own](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#naming-your-own-fallback-models). Either way, you get back one response that names the model that answered, so your user gets an answer in one round trip.212213<Note>214  Server-side fallback is in beta on the Claude API. The `fallbacks` parameter is not supported on the [Message Batches API](https://platform.claude.com/docs/en/build-with-claude/batch-processing) (a batch item that includes it comes back as an errored result) and is not available on Amazon Bedrock, Google Cloud, or Microsoft Foundry. On those platforms, use [client-side fallback with the SDK middleware](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#client-side-fallback) instead.215</Note>216217### Making the request218219Set the `fallbacks` parameter to the string `"default"` and send the `server-side-fallback-2026-07-01` beta header. The API then applies the requested model's server-defined default routing, which selects a recommended fallback model based on the refusal category the classifier reports, so refused requests are served without you maintaining a model list as recommendations change.220221Default routing never draws the up-front [oversized-image rejection](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#oversized-image-error) for models you did not choose: a routed model that would resize an image marked `"oversized_image": "error"` is dropped from the routing instead, so a marked image is never served resized.222223<CodeGroup>224  ```bash cURL225  curl --fail-with-body -sS https://api.anthropic.com/v1/messages \226    -H "x-api-key: $ANTHROPIC_API_KEY" \227    -H "anthropic-version: 2023-06-01" \228    -H "anthropic-beta: server-side-fallback-2026-07-01" \229    -H "content-type: application/json" \230    -d '{231      "model": "claude-fable-5",232      "max_tokens": 1024,233      "fallbacks": "default",234      "messages": [{"role": "user", "content": "Hello, Claude"}]235    }' |236    jq -c '{237      stop_reason,238      model,239      # A fallback_message entry in usage.iterations means a fallback model ran;240      # pair it with stop_reason to confirm the fallback served the response.241      served_by_fallback: (242        any(.usage.iterations[]?; .type == "fallback_message")243        and .stop_reason != "refusal"244      )245    }'246  ```247248  ```bash CLI249  ant beta:messages create \250    --model claude-fable-5 \251    --max-tokens 1024 \252    --message '{"role":"user","content":"Hello, Claude"}' \253    --fallbacks default \254    --beta server-side-fallback-2026-07-01 \255    --format json |256    jq -c '{257      stop_reason,258      model,259      # A fallback_message entry in usage.iterations means a fallback model ran;260      # pair it with stop_reason to confirm the fallback served the response.261      served_by_fallback: (262        any(.usage.iterations[]?; .type == "fallback_message")263        and .stop_reason != "refusal"264      )265    }'266  ```267268  ```python Python269  client = Anthropic()270271  response = client.beta.messages.create(272      model="claude-fable-5",273      max_tokens=1024,274      messages=[{"role": "user", "content": "Hello, Claude"}],275      fallbacks="default",276      betas=["server-side-fallback-2026-07-01"],277  )278279  # A fallback_message entry in usage.iterations means a fallback model ran;280  # pair it with stop_reason to confirm the fallback served the response.281  fallback_ran = any(282      iteration.type == "fallback_message"283      for iteration in response.usage.iterations or []284  )285  served_by_fallback = fallback_ran and response.stop_reason != "refusal"286287  print(288      json.dumps(289          {290              "stop_reason": response.stop_reason,291              "model": response.model,292              "served_by_fallback": served_by_fallback,293          }294      )295  )296  ```297298  ```typescript TypeScript299  const client = new Anthropic();300301  const response = await client.beta.messages.create({302    model: "claude-fable-5",303    max_tokens: 1024,304    messages: [{ role: "user", content: "Hello, Claude" }],305    fallbacks: "default",306    betas: ["server-side-fallback-2026-07-01"]307  });308309  // A fallback_message entry in usage.iterations means a fallback model ran;310  // pair it with stop_reason to confirm the fallback served the response.311  const { stop_reason, model, usage } = response;312  const servedByFallback =313    (usage.iterations ?? []).some((entry) => entry.type === "fallback_message") &&314    stop_reason !== "refusal";315316  console.log(317    JSON.stringify({318      stop_reason,319      model,320      served_by_fallback: servedByFallback321    })322  );323  ```324325  ```csharp C#326  AnthropicClient client = new();327328  var response = await client.Beta.Messages.Create(329      new()330      {331          Model = Messages::Model.ClaudeFable5,332          MaxTokens = 1024,333          Messages =334          [335              new() { Content = "Hello, Claude", Role = Role.User },336          ],337          Fallbacks = new Default(),338          Betas = [AnthropicBeta.ServerSideFallback2026_07_01],339      }340  );341342  // A fallback_message entry in usage.iterations means a fallback model ran;343  // pair it with stop_reason to confirm the fallback served the response.344  bool fallbackRan = (response.Usage.Iterations ?? []).Any(iteration =>345      iteration.TryPickBetaFallbackMessageIterationUsage(out _)346  );347  bool servedByFallback =348      fallbackRan && response.StopReason?.Value() != BetaStopReason.Refusal;349350  Console.WriteLine(351      JsonSerializer.Serialize(352          new353          {354              stop_reason = response.StopReason?.Raw(),355              model = response.Model.Raw(),356              served_by_fallback = servedByFallback,357          }358      )359  );360  ```361362  ```go Go363  client := anthropic.NewClient()364365  response, err := client.Beta.Messages.New(context.Background(), anthropic.BetaMessageNewParams{366  	Model:     anthropic.ModelClaudeFable5,367  	MaxTokens: 1024,368  	Messages: []anthropic.BetaMessageParam{369  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude")),370  	},371  	Fallbacks: anthropic.BetaFallbacksParamOfDefault(),372  	Betas:     []anthropic.AnthropicBeta{anthropic.AnthropicBetaServerSideFallback2026_07_01},373  })374  if err != nil {375  	panic(err)376  }377378  // A fallback_message entry in usage.iterations means a fallback model ran;379  // pair it with stop_reason to confirm the fallback served the response.380  fallbackRan := slices.ContainsFunc(381  	response.Usage.Iterations,382  	func(iteration anthropic.BetaIterationsUsageItemUnion) bool {383  		_, isFallback := iteration.AsAny().(anthropic.BetaFallbackMessageIterationUsage)384  		return isFallback385  	},386  )387  servedByFallback := fallbackRan && response.StopReason != anthropic.BetaStopReasonRefusal388389  summary, err := json.Marshal(struct {390  	StopReason       anthropic.BetaStopReason `json:"stop_reason"`391  	Model            anthropic.Model          `json:"model"`392  	ServedByFallback bool                     `json:"served_by_fallback"`393  }{response.StopReason, response.Model, servedByFallback})394  if err != nil {395  	panic(err)396  }397  fmt.Println(string(summary))398  ```399400  ```java Java401  AnthropicClient client = AnthropicOkHttpClient.fromEnv();402403  BetaMessage response = client.beta().messages().create(404      MessageCreateParams.builder()405          .model(Model.CLAUDE_FABLE_5)406          .maxTokens(1024L)407          .addUserMessage("Hello, Claude")408          .fallbacksDefault()409          .addBeta(AnthropicBeta.SERVER_SIDE_FALLBACK_2026_07_01)410          .build()411  );412413  // A fallback_message usage entry means a fallback model produced the414  // response; a refusal stop reason means no model served it.415  List<BetaUsage.Iteration> iterations =416      response.usage().iterations().orElse(List.of());417  boolean servedByFallback =418      iterations.stream().anyMatch(BetaUsage.Iteration::isFallbackMessage)419          && response.stopReason().filter(BetaStopReason.REFUSAL::equals).isEmpty();420421  IO.println("""422      {"stop_reason":"%s","model":"%s","served_by_fallback":%b}\423      """.formatted(424          response.stopReason().map(BetaStopReason::asString).orElse("null"),425          response.model().asString(),426          servedByFallback));427  ```428429  ```php PHP430  $client = new Client();431432  $response = $client->beta->messages->create(433      maxTokens: 1024,434      messages: [['role' => 'user', 'content' => 'Hello, Claude']],435      model: 'claude-fable-5',436      fallbacks: 'default',437      betas: ['server-side-fallback-2026-07-01'],438  );439440  // A fallback_message entry in usage.iterations means a fallback model ran;441  // pair it with stop_reason to confirm the fallback served the response.442  $iterations = $response->usage->iterations ?? [];443  $servedByFallback = array_any($iterations, fn($entry) => $entry->type === 'fallback_message')444      && $response->stopReason !== 'refusal';445446  echo json_encode([447      'stop_reason' => $response->stopReason,448      'model' => $response->model,449      'served_by_fallback' => $servedByFallback,450  ]), PHP_EOL;451  ```452453  ```ruby Ruby454  client = Anthropic::Client.new455456  response = client.beta.messages.create(457    model: "claude-fable-5",458    max_tokens: 1024,459    messages: [{role: "user", content: "Hello, Claude"}],460    fallbacks: :default,461    betas: ["server-side-fallback-2026-07-01"]462  )463464  # A fallback_message entry in usage.iterations means a fallback model ran;465  # pair it with stop_reason to confirm the fallback served the response.466  iterations = response.usage.iterations || []467  served_by_fallback = iterations.any? { it.type == :fallback_message } &&468    response.stop_reason != :refusal469470  stop_reason = response.stop_reason471  model = response.model472  puts JSON.generate({stop_reason:, model:, served_by_fallback:})473  ```474</CodeGroup>475476Anthropic sets safeguards for each model individually and for each policy category, in line with the model's capability: depending on the category, a flagged request may fall back to a less capable model or be declined. The `"default"` mode encodes these per-model, per-category recommendations for you, so a refused request is retried on the model Anthropic recommends for that category. Fallbacks are visible either way: the response names the model that served it, and the `fallback` content block marks the handoff.477478The routing is applied server-side and is not published per model on the [Models API](https://platform.claude.com/docs/en/api/models/list). To see which model served a refused request, check the response's top-level `model` field and look for a `fallback_message` entry in `usage.iterations`, as this page's samples do.479480Only a safety classifier decline triggers the fallback. A rate limit, overload, or server error on the requested model is returned to you as-is.481482<Note>483  The beta header must carry exactly the date `2026-07-01`, which supports both `"default"` and the explicit-list form, or `2026-06-01`, which accepts only the explicit-list form. Under any other `server-side-fallback-*` value, the `fallbacks` parameter is rejected with a 400 error. If you built against an earlier preview of this feature, update the beta header and the request and response shapes together to the ones on this page.484</Note>485486### Naming your own fallback models487488Instead of default routing, you can set `fallbacks` to a list of up to three models. When the requested model declines, the API runs the next model in the chain on the same request. Use this form when you want to control exactly which models serve refused requests, such as pinning a model your application has qualified.489490Named fallback models count toward the [oversized-image check](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#oversized-image-error): a request whose image block sets `"oversized_image": "error"` is checked up front against the requested model and every named fallback, is rejected if any of them would resize that image, and the rejection's reported rescale target fits them all.491492The highlighted lines are the only difference from the default-routing request.493494<CodeGroup>495  ```bash cURL496  curl --fail-with-body -sS https://api.anthropic.com/v1/messages \497    -H "x-api-key: $ANTHROPIC_API_KEY" \498    -H "anthropic-version: 2023-06-01" \499    -H "anthropic-beta: server-side-fallback-2026-07-01" \500    -H "content-type: application/json" \501    -d '{502      "model": "claude-fable-5",503      "max_tokens": 1024,504      "fallbacks": [{"model": "claude-opus-4-8"}],505      "messages": [{"role": "user", "content": "Hello, Claude"}]506    }'507  ```508509  ```bash CLI510  ant beta:messages create \511    --model claude-fable-5 \512    --max-tokens 1024 \513    --message '{"role":"user","content":"Hello, Claude"}' \514    --fallbacks '[{"model":"claude-opus-4-8"}]' \515    --beta server-side-fallback-2026-07-01516  ```517518  ```python Python519  client = Anthropic()520521  response = client.beta.messages.create(522      model="claude-fable-5",523      max_tokens=1024,524      messages=[{"role": "user", "content": "Hello, Claude"}],525      fallbacks=[{"model": "claude-opus-4-8"}],526      betas=["server-side-fallback-2026-07-01"],527  )528  print(response.model)529  ```530531  ```typescript TypeScript532  const client = new Anthropic();533534  const response = await client.beta.messages.create({535    model: "claude-fable-5",536    max_tokens: 1024,537    messages: [{ role: "user", content: "Hello, Claude" }],538    fallbacks: [{ model: "claude-opus-4-8" }],539    betas: ["server-side-fallback-2026-07-01"]540  });541  console.log(response.model);542  ```543544  ```csharp C#545  AnthropicClient client = new();546547  BetaMessage response = await client.Beta.Messages.Create(548      new()549      {550          Model = Messages::Model.ClaudeFable5,551          MaxTokens = 1024,552          Messages = [new() { Content = "Hello, Claude", Role = Role.User }],553          Fallbacks = new([new(Messages::Model.ClaudeOpus4_8)]),554          Betas = [AnthropicBeta.ServerSideFallback2026_07_01],555      }556  );557558  Console.WriteLine(response.Model.Raw());559  ```560561  ```go Go562  client := anthropic.NewClient()563564  response, err := client.Beta.Messages.New(context.Background(), anthropic.BetaMessageNewParams{565  	Model:     anthropic.ModelClaudeFable5,566  	MaxTokens: 1024,567  	Messages: []anthropic.BetaMessageParam{568  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude")),569  	},570  	Fallbacks: anthropic.BetaFallbacksParamUnion{571  		OfBetaFallbackArray: []anthropic.BetaFallbackParam{{Model: anthropic.ModelClaudeOpus4_8}},572  	},573  	Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaServerSideFallback2026_07_01},574  })575  if err != nil {576  	panic(err)577  }578579  fmt.Println(response.Model)580  ```581582  ```java Java583  AnthropicClient client = AnthropicOkHttpClient.fromEnv();584585  BetaMessage response = client.beta().messages().create(MessageCreateParams.builder()586      .model(Model.CLAUDE_FABLE_5)587      .maxTokens(1024L)588      .addUserMessage("Hello, Claude")589      .fallbacksOfFallbackParams(List.of(BetaFallbackParam.builder()590          .model(Model.CLAUDE_OPUS_4_8)591          .build()))592      .addBeta(AnthropicBeta.SERVER_SIDE_FALLBACK_2026_07_01)593      .build());594595  IO.println(response.model().asString());596  ```597598  ```php PHP599  $client = new Client();600601  $response = $client->beta->messages->create(602      model: 'claude-fable-5',603      maxTokens: 1024,604      messages: [['role' => 'user', 'content' => 'Hello, Claude']],605      fallbacks: [['model' => 'claude-opus-4-8']],606      betas: ['server-side-fallback-2026-07-01'],607  );608609  echo $response->model, PHP_EOL;610  ```611612  ```ruby Ruby613  client = Anthropic::Client.new614615  response = client.beta.messages.create(616    model: "claude-fable-5",617    max_tokens: 1024,618    messages: [{role: "user", content: "Hello, Claude"}],619    fallbacks: [{model: "claude-opus-4-8"}],620    betas: ["server-side-fallback-2026-07-01"]621  )622623  puts response.model624  ```625</CodeGroup>626627A few rules apply to the `fallbacks` list:628629* Entries are tried in order. Each must be distinct from the other entries and from the requested model.630* Each entry must be one of the requested model's permitted targets. With the beta header set, that list is published as `allowed_fallback_models` on the model's entry in the [Models API](https://platform.claude.com/docs/en/api/models/list).631* Each entry names a `model` and can override `max_tokens`, `thinking`, `output_config`, and `speed` for that attempt only.632* The request must be valid as a direct request to every model named. If a fallback model does not support a feature the request uses, the API rejects the request up front.633* As with the default mode, only a safety classifier decline triggers the fallback. A rate limit, overload, or server error on the requested model is returned to you as-is.634* If a fallback model is rate limited or overloaded, the fallback attempt is not made and the preceding refusal is returned instead. The refusal's `stop_details.recommended_model` then names a model to retry directly. Size the fallback model's rate limits for the refusal volume you expect, or fallbacks degrade to refusals under load.635636The response has the same shape in both modes: the model that served the turn appears in the top-level `model` field, a `fallback` content block marks the handoff, and `usage.iterations` records each attempt.637638### What the response contains639640The response looks like any other message, with two additions:641642* The top-level `model` field reports the model that produced the returned message, whether that is the requested model or a fallback.643644* A `fallback` content block marks each point in `content` where one model's output gives way to the next: `{"type": "fallback", "from": {"model": ...}, "to": {"model": ...}}`.645646  * `from.model` echoes the model string you sent when the declining hop is the requested model.647  * `to.model` is always the resolved ID of the model that continues.648649On a refusal before any output, the `fallback` block is the first content block. For example, when default routing selects Claude Opus 4.8 for the refusal's category:650651```json652{653  "id": "msg_01XFUDYJgAACzvnptvVoYEL",654  "type": "message",655  "role": "assistant",656  "model": "claude-opus-4-8",657  "content": [658    {659      "type": "fallback",660      "from": { "model": "claude-fable-5" },661      "to": { "model": "claude-opus-4-8" }662    },663    { "type": "text", "text": "Hi! How can I help you today?" }664  ],665  "stop_reason": "end_turn",666  "stop_details": null,667  "usage": {668    "input_tokens": 412,669    "output_tokens": 264,670    "cache_read_input_tokens": 0,671    "cache_creation_input_tokens": 0,672    "iterations": [673      {674        "type": "message",675        "model": "claude-fable-5",676        "input_tokens": 535,677        "output_tokens": 0,678        "cache_read_input_tokens": 0,679        "cache_creation_input_tokens": 0680      },681      {682        "type": "fallback_message",683        "model": "claude-opus-4-8",684        "input_tokens": 412,685        "output_tokens": 264,686        "cache_read_input_tokens": 0,687        "cache_creation_input_tokens": 0688      }689    ]690  }691}692```693694The `usage.iterations` array records every attempt. A model that declined appears as an ordinary `message` entry, and the model that served the turn appears as a `fallback_message` entry. If every model in the chain declines, the response is the last model's refusal, with a `message` entry for each earlier hop and a `fallback_message` entry for the last.695696[Sticky routing](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#sticky-routing) can send a later turn straight to the fallback model. Such a turn carries no `fallback` content block, because no model declined that turn. Identify it by the `fallback_message` entry in `usage.iterations`, the absence of a `message` entry for the requested model, and the response's `model` field.697698### Continuing the conversation699700On the next turn, send the assistant content back as you received it. After a mid-output fallback, `content` can include block types the declining model produced before the handoff. The following table covers which to keep and which to drop when you echo the turn.701702| Block type                                                                             | On the next turn                                                                                                                                                                                                               |703| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |704| `fallback`                                                                             | Keep it exactly where it appeared. The API uses its position to validate the thinking blocks around it, so a request that echoes thinking blocks from both sides of the boundary is rejected if the block is omitted or moved. |705| `text`                                                                                 | Keep.                                                                                                                                                                                                                          |706| Any block after the final `fallback` block                                             | Keep.                                                                                                                                                                                                                          |707| `thinking`, `redacted_thinking`, or `connector_text` before the final `fallback` block | Drop.                                                                                                                                                                                                                          |708| Client-side `tool_use` before the final `fallback` block                               | Drop.                                                                                                                                                                                                                          |709| `server_tool_use` before the final `fallback` block                                    | Keep when paired with its result. Drop when it has no matching result.                                                                                                                                                         |710711<Note>712  A `connector_text` block carries narration text that some tool-using responses include between tool calls.713</Note>714715### Streaming716717On a streaming request, the retry happens on the same stream, and nothing you have already received is invalidated. What you see depends on when the decline happens.718719**When the decline happens before any output:**720721* `message_start` names the fallback model, and the `fallback` block is the first content block.722* Because `message_start` waits for the fallback attempt to start, time to first byte includes the declined attempt.723724**When the decline happens mid-output:**725726* The open content block closes, and the `fallback` block (an ordinary `content_block_start` and `content_block_stop` pair with no deltas) marks the boundary.727* The fallback model continues from the partial output. Only the partial output's `text` blocks are passed to the fallback model as context. Other block types remain in `content`.728* `message_start` already named the requested model, so read the serving model from the `fallback` block's `to.model` and from the `fallback_message` entry in the final `message_delta`'s `usage.iterations`.729730### Non-streaming responses731732On a non-streaming request, a mid-output decline behaves differently: the response omits the declined model's partial output, and the fallback model answers from scratch. The result looks like a decline before any output, with the `fallback` block first. The declined attempt and its output tokens still appear in `usage.iterations`.733734<Note>735  **Declines during tool use:** completed tool work does not block fallback. When a decline fires after server tools (for example, web search or code execution) have finished executing within a request, the fallback attempt proceeds: the completed tool results carry over, and the fallback model can keep invoking server tools. The one case that does not retry is a streaming decline that fires while a tool-use block of any type (a client tool, a server tool, or an MCP tool call) is still open on the stream: that refusal is returned directly, and if the `fallback-credit-2026-07-01` header is set it still carries a credit token redeemable by continuing the partial response. Non-streaming requests are unaffected; the API clears the partial work and retries before responding.736</Note>737738### Billing and rate limits739740An attempt that declined before producing any output is not billed: its tokens are reported on its `usage.iterations` entry but not charged. Every attempt that produced output, including one that declined partway through its response, is billed separately at the rates of the model that ran it. The `usage.iterations` array is the per-attempt record of what you're billed. The top-level `usage` counts describe only the attempt that produced the returned message. Tokens from different models are never summed into one field.741742Every attempt that runs, including one that declined, counts against its own model's rate limits.743744### Sticky routing745746After a conversation falls back, the API records which model served it. Later requests for that conversation that include `fallbacks` go directly to that fallback model, without running the requested model. This avoids paying for an attempt that would predictably be declined again on every turn.747748A few properties of the routing decision:749750* It is retained for approximately 1 hour and is scoped to your organization.751* It is stored as a content hash of the conversation prefix plus the model that served it. The message content itself is not stored.752* It is best-effort, so your code must handle the requested model being tried again at any time.753754Sticky routing applies to both streaming and non-streaming requests. On a streaming request, the routing decision is made before the stream opens, so the `message_start` event's `model` field already carries the fallback model's ID.755756## Client-side fallback with the SDK middleware757758Every Anthropic SDK includes a refusal-fallback middleware. You configure it once on the client with your list of fallback models. Calls through `client.beta.messages` then retry refused requests automatically, on any platform. The middleware also sends the `fallback-credit-2026-07-01` beta header on every request it handles, so retries are repriced without per-request setup.759760### Setting it up761762Pass the middleware to the client constructor, and share one `BetaFallbackState` instance across the requests of a conversation.763764<CodeGroup>765  ```bash cURL766  # The refusal-fallback middleware is an SDK feature. See the767  # server-side fallback section for the equivalent single-request approach,768  # or the fallback credit page for the raw HTTP retry pattern.769  ```770771  ```bash CLI772  # The refusal-fallback middleware is an SDK feature. See the773  # server-side fallback section for the equivalent single-request approach,774  # or the fallback credit page for the raw HTTP retry pattern.775  ```776777  ```python Python778  from anthropic import Anthropic, BetaFallbackState, BetaRefusalFallbackMiddleware779780  # On a refusal, the middleware retries on the listed fallback model and781  # automatically sends the fallback-credit beta header on every request it handles.782  client = Anthropic(783      middleware=[BetaRefusalFallbackMiddleware([{"model": "claude-opus-4-8"}])],784  )785786  state = BetaFallbackState()  # pins follow-ups to the model that accepted787788  # Streaming: on a refusal the middleware retries on the fallback model and789  # splices its events onto the open stream.790  with (791      state,792      client.beta.messages.stream(793          max_tokens=1024,794          model="claude-fable-5",795          messages=[{"role": "user", "content": "Hello, Claude"}],796      ) as stream,797  ):798      for text in stream.text_stream:799          print(text, end="", flush=True)800      final_message = stream.get_final_message()801  print(f"\nserved by: {final_message.model}")802803  # Non-streaming: reusing the state keeps the conversation pinned.804  with state:805      message = client.beta.messages.create(806          max_tokens=1024,807          model="claude-fable-5",808          messages=[{"role": "user", "content": "Hello, Claude"}],809      )810  print(f"served by: {message.model}")811  ```812813  ```typescript TypeScript814  import { BetaFallbackState, betaRefusalFallbackMiddleware } from "@anthropic-ai/sdk";815816  // On a refusal, the middleware retries on the listed fallback model and817  // automatically sends the fallback-credit beta header on every request it handles.818  const client = new Anthropic({819    middleware: [betaRefusalFallbackMiddleware([{ model: "claude-opus-4-8" }])]820  });821822  // Share one state across the conversation so follow-up requests stay823  // pinned to the model that accepted.824  const fallbackState = new BetaFallbackState();825826  // Streaming: on a refusal the middleware retries on the fallback model and827  // splices its events onto the open stream.828  const stream = client.beta.messages829    .stream(830      {831        max_tokens: 1024,832        model: "claude-fable-5",833        messages: [{ role: "user", content: "Hello, Claude" }]834      },835      { fallbackState }836    )837    .on("text", (text) => process.stdout.write(text));838839  const finalMessage = await stream.finalMessage();840  console.log("\nserved by:", finalMessage.model);841842  // Non-streaming: reusing the state keeps the conversation pinned.843  const message = await client.beta.messages.create(844    {845      max_tokens: 1024,846      model: "claude-fable-5",847      messages: [{ role: "user", content: "Hello, Claude" }]848    },849    { fallbackState }850  );851  console.log("served by:", message.model);852  ```853854  ```csharp C#855  using Anthropic;856  using Anthropic.Helpers;857  using Anthropic.Models.Beta.Messages;858  using Messages = Anthropic.Models.Messages;859860  // On a refusal, the handler retries on the listed fallback model and861  // automatically sends the fallback-credit beta header on every request it handles.862  AnthropicClient client = new()863  {864      Handlers =865      [866          new BetaRefusalFallbackHandler { Fallbacks = [new(Messages::Model.ClaudeOpus4_8)] },867      ],868  };869870  // Pins follow-up requests sharing this state to the model that accepted.871  BetaFallbackState fallbackState = BetaFallbackState.Create();872873  MessageCreateParams parameters = new()874  {875      Model = Messages::Model.ClaudeFable5,876      MaxTokens = 1024,877      Messages = [new() { Content = "Hello, Claude", Role = Role.User }],878  };879880  // Streaming: if the stream ends in a refusal, the handler splices the fallback881  // model's events onto the still-open stream.882  BetaMessageContentAggregator aggregator = new();883  using (fallbackState.Use())884  {885      var responseUpdates = client.Beta.Messages.CreateStreaming(parameters);886      await foreach (BetaRawMessageStreamEvent rawEvent in responseUpdates.CollectAsync(aggregator))887      {888          if (889              rawEvent.TryPickContentBlockDelta(out var deltaEvent)890              && deltaEvent.Delta.TryPickText(out var textDelta)891          )892          {893              Console.Write(textDelta.Text);894          }895      }896  }897  BetaMessage streamedMessage = aggregator.Message();898  Console.WriteLine($"\nserved by: {streamedMessage.Model.Raw()}");899900  // Non-streaming: reusing the state keeps the conversation pinned to the model that accepted.901  using (fallbackState.Use())902  {903      BetaMessage message = await client.Beta.Messages.Create(parameters);904      Console.WriteLine($"served by: {message.Model.Raw()}");905  }906  ```907908  ```go Go909  import (910  // ...911  	"github.com/anthropics/anthropic-sdk-go/lib/betafallback"912  // ...913  )914915  func main() {916  	ctx := context.Background()917918  	// The middleware retries a refused request on each fallback model in919  	// turn, and opts requests into the fallback-credit beta automatically.920  	client := anthropic.NewClient(921  		option.WithMiddleware(betafallback.BetaRefusalFallbackMiddleware(922  			[]anthropic.BetaFallbackParam{{Model: anthropic.ModelClaudeOpus4_8}},923  		)),924  	)925926  	// One state per conversation: requests sharing it stay pinned to the927  	// model that accepted, so a follow-up never re-asks a model that refused.928  	state := &betafallback.BetaFallbackState{}929  	conversation := betafallback.WithBetaFallbackState(state)930931  	params := anthropic.BetaMessageNewParams{932  		MaxTokens: 1024,933  		Model:     anthropic.ModelClaudeFable5,934  		Messages: []anthropic.BetaMessageParam{935  			anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude")),936  		},937  	}938939  	// Streaming: on a refusal the middleware retries in place, splicing the940  	// fallback model's events onto the open stream as one continuous message.941  	stream := client.Beta.Messages.NewStreaming(ctx, params, conversation)942  	defer stream.Close()943  	var streamed anthropic.BetaMessage944  	for stream.Next() {945  		event := stream.Current()946  		if err := streamed.Accumulate(event); err != nil {947  			panic(err)948  		}949  		switch eventVariant := event.AsAny().(type) {950  		case anthropic.BetaRawContentBlockDeltaEvent:951  			if textDelta, ok := eventVariant.Delta.AsAny().(anthropic.BetaTextDelta); ok {952  				fmt.Print(textDelta.Text)953  			}954  		}955  	}956  	if err := stream.Err(); err != nil {957  		panic(err)958  	}959  	fmt.Println("\nserved by:", streamed.Model)960961  	// Non-streaming: the shared state pins this follow-up to the model that962  	// served the streamed turn.963  	message, err := client.Beta.Messages.New(ctx, params, conversation)964  	if err != nil {965  		panic(err)966  	}967  	fmt.Println("served by:", message.Model)968  }969  ```970971  ```java Java972  import com.anthropic.client.AnthropicClient;973  import com.anthropic.client.okhttp.AnthropicOkHttpClient;974  import com.anthropic.core.RequestOptions;975  import com.anthropic.core.http.StreamResponse;976  import com.anthropic.helpers.BetaFallbackState;977  import com.anthropic.helpers.BetaMessageAccumulator;978  import com.anthropic.helpers.BetaRefusalFallbackInterceptor;979  import com.anthropic.models.beta.messages.BetaMessage;980  import com.anthropic.models.beta.messages.BetaRawMessageStreamEvent;981  import com.anthropic.models.beta.messages.MessageCreateParams;982  import com.anthropic.models.messages.Model;983984  void main() {985      // The interceptor retries refused requests on the fallback model. It automatically986      // adds the fallback-credit beta header to every request it handles.987      AnthropicClient client = AnthropicOkHttpClient.builder()988          .fromEnv()989          .addInterceptor(BetaRefusalFallbackInterceptor.builder()990              .addFallback(Model.CLAUDE_OPUS_4_8)991              .build())992          .build();993994      // Share one state across requests so follow-ups stay pinned to the model that accepted.995      BetaFallbackState state = BetaFallbackState.create();996997      MessageCreateParams params = MessageCreateParams.builder()998          .model(Model.CLAUDE_FABLE_5)999          .maxTokens(1024)1000          .addUserMessage("Hello, Claude")1001          .build();10021003      // Streaming: on a refusal, the fallback model's events are spliced onto the open stream.1004      BetaMessageAccumulator accumulator = BetaMessageAccumulator.create();1005      try (StreamResponse<BetaRawMessageStreamEvent> streamResponse = client.beta()1006              .messages()1007              .createStreaming(params, RequestOptions.builder().fallbackState(state).build())) {1008          streamResponse.stream()1009              .peek(accumulator::accumulate)1010              .forEach(event -> event.contentBlockDelta()1011                  .flatMap(deltaEvent -> deltaEvent.delta().text())1012                  .ifPresent(textDelta -> IO.print(textDelta.text())));1013      }1014      IO.println("\nserved by: " + accumulator.message().model().asString());10151016      // Non-streaming: reusing the same state keeps the conversation pinned.1017      BetaMessage message = client.beta()1018          .messages()1019          .create(params, RequestOptions.builder().fallbackState(state).build());1020      IO.println("served by: " + message.model().asString());1021  }1022  ```10231024  ```php PHP1025  use Anthropic\Beta\Messages\BetaRawContentBlockDeltaEvent;1026  use Anthropic\Beta\Messages\BetaTextDelta;1027  use Anthropic\Client;1028  use Anthropic\Lib\Middleware\BetaFallbackState;1029  use Anthropic\Lib\Middleware\RefusalFallbackMiddleware;1030  use Anthropic\Lib\Streaming\MessageAccumulator;10311032  // Configure the fallback chain once. On a refusal, the middleware retries the1033  // request down the chain and sends the fallback-credit beta header for you.1034  $client = new Client(1035      requestOptions: [1036          'middleware' => [new RefusalFallbackMiddleware([['model' => 'claude-opus-4-8']])],1037      ],1038  );10391040  // Share one state across the conversation so follow-up requests stay pinned1041  // to the model that accepted.1042  $state = new BetaFallbackState();10431044  // Streaming: on a refusal the middleware splices the fallback model's events1045  // onto the still-open stream. The accumulator's model is the serving model.1046  $stream = $client->beta->messages->createStream(1047      model: 'claude-fable-5',1048      maxTokens: 1024,1049      messages: [['role' => 'user', 'content' => 'Hello, Claude']],1050      requestOptions: ['fallbackState' => $state],1051  );1052  $accumulator = MessageAccumulator::forBetaMessages();1053  foreach ($stream as $event) {1054      $accumulator->accumulate($event);1055      if ($event instanceof BetaRawContentBlockDeltaEvent1056          && $event->delta instanceof BetaTextDelta) {1057          echo $event->delta->text;1058      }1059  }1060  echo "\nserved by: {$accumulator->message()->model}\n";10611062  // Non-streaming: same middleware. Reusing the state keeps the conversation1063  // pinned to the model that accepted.1064  $message = $client->beta->messages->create(1065      model: 'claude-fable-5',1066      maxTokens: 1024,1067      messages: [['role' => 'user', 'content' => 'Hello, Claude']],1068      requestOptions: ['fallbackState' => $state],1069  );1070  echo "served by: {$message->model}\n";1071  ```10721073  ```ruby Ruby1074  # On a refusal, the middleware retries the request down the fallback chain.1075  # It sends the fallback-credit beta header on every request it handles.1076  client = Anthropic::Client.new(1077    middleware: [Anthropic::BetaRefusalFallbackMiddleware.new([{model: "claude-opus-4-8"}])]1078  )10791080  # Share one state across the conversation so follow-up requests stay1081  # pinned to the model that accepted.1082  state = Anthropic::BetaFallbackState.new10831084  # Streaming: on a refusal the middleware splices the fallback model's1085  # events onto the still-open stream.1086  stream = client.beta.messages.stream(1087    model: "claude-fable-5",1088    max_tokens: 1024,1089    messages: [{role: "user", content: "Hello, Claude"}],1090    request_options: {fallback_state: state}1091  )1092  stream.text.each { print it }1093  puts "\nserved by: #{stream.accumulated_message.model}"10941095  # Non-streaming: reusing the state keeps the conversation pinned to the model that accepted.1096  message = client.beta.messages.create(1097    model: "claude-fable-5",1098    max_tokens: 1024,1099    messages: [{role: "user", content: "Hello, Claude"}],1100    request_options: {fallback_state: state}1101  )1102  puts "served by: #{message.model}"1103  ```1104</CodeGroup>11051106### How it behaves11071108* Retries walk your fallback list in order. A fallback model that itself refuses passes the request to the next entry.1109* 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.1110* Thinking blocks from Claude Fable 5.1 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. The fallback model can't read Claude Fable 5.1 blocks, which are [preserved only for that model or a newer one](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-for-model), so the API drops them.1111* 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.1112* The model that accepted is recorded in `BetaFallbackState`, so follow-up requests that share the state stay pinned to it rather than re-asking a model that refused.11131114<Note>1115  The middleware and the server-side `fallbacks` parameter do the same job. Configure one or the other, never both on the same request. To send a server-side `fallbacks` request from an application that installs the middleware, use a separate client instance without it.1116</Note>11171118## Writing the retry yourself11191120Over raw HTTP or with custom retry logic, implement the pattern the middleware wraps:11211122<Steps>1123  <Step title="Detect the refusal">1124    Check the response for `stop_reason: "refusal"`.1125  </Step>11261127  <Step title="Re-send on a fallback model">1128    Send the same request with `model` set to a fallback model, such as Claude Opus 4.8. Another model can normally serve a request that 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):11291130    * **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 cannot use them either way: it ignores Claude Fable 5 blocks, and Claude Fable 5.1 blocks are [preserved only for that model or a newer one](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-for-model), so the API drops them.1131    * **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)).1132  </Step>11331134  <Step title="Stay on the fallback model">1135    For multi-turn conversations, keep using the fallback model for subsequent turns rather than switching back.1136  </Step>1137</Steps>11381139A manual retry writes the fallback model's prompt cache from scratch, which costs more than reading an existing cache. [Fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit) refunds that cost; redeem it on every retry you build yourself.11401141## Refusals in Message Batches11421143A refused request in a [Message Batch](https://platform.claude.com/docs/en/build-with-claude/batch-processing) comes back as `result.type: "succeeded"` with `stop_reason: "refusal"`. Batch results carry the same `stop_details` object as synchronous responses, so you can detect refusals through either `stop_reason` or `stop_details.type`. One difference: batch refusals don't mint fallback credits, so `stop_details` on a batch result never includes a `fallback_credit_token`.11441145Server-side fallback is not available for batches (a batch request that includes `fallbacks` produces a per-item errored result). To retry refused batch items:114611471. Collect the refused items from the results.11482. Strip the Claude Fable 5.1 or Claude Fable 5 thinking blocks from any multi-turn histories.11493. Resubmit them on a fallback model as a new batch or as direct requests.11501151## Common pitfalls11521153* **Retry on a different model.** Re-sending a refused request to the same model usually earns another refusal. Point the retry at the fallback model.1154* **Budget retries per request, not per turn or per session.** A single turn can produce several refusals, for example an agent plus its sub-agents.1155* **Configure fallback on every request path.** Retry handlers, error-recovery branches, and background workers all need it. A handler that re-issues a request without fallback loses the protection on exactly the requests most likely to need it.1156* **Give sub-agent calls their own fallback.** The `fallbacks` parameter does not propagate into model calls made from inside tool execution.1157* **Make fallback a property of the request, not of ambient state.** A shared flag, cached config value, or global toggle can drift out of sync and silently leave a request unprotected. When you cannot confirm fallback is active, configure it rather than assume it is on.1158* **Instrument refusals as their own signal.** A refusal is an HTTP 200, so monitoring built on error rates or 5xx responses never sees it. Emit one event per refusal and one per fallback-served response (the `fallback_message` entry in `usage.iterations` marks the latter), then alert on the gap between the two counts.1159* **Branch on `stop_reason` or `stop_details.type`, not on `content` or the inner `stop_details` fields.** The `stop_details` object is always present on a refusal, but its `category` and `explanation` fields can be `null`. Check for `stop_reason` equal to `"refusal"` directly.11601161## Next steps11621163<CardGroup>1164  <Card title="Fallback credit" icon="scales" href="https://platform.claude.com/docs/en/build-with-claude/fallback-credit">1165    Avoid paying the prompt-cache cost twice when you build the retry yourself.1166  </Card>11671168  <Card title="Stop reasons and fallback" icon="code" href="https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons">1169    Every `stop_reason` value and how to handle it.1170  </Card>11711172  <Card title="SDK middleware" icon="settings" href="https://platform.claude.com/docs/en/cli-sdks-libraries/middleware">1173    How SDK middleware works, including the refusal-fallback helper.1174  </Card>11751176  <Card title="Migration guide" icon="arrow-right" href="https://platform.claude.com/docs/en/models/fable-5-1/migration-guide">1177    Move an existing application to Claude Fable 5.1.1178  </Card>1179</CardGroup>1180
Files main
Menu

Theme