SPB Git

Repository Public

fallback-credit.md 31.9 KB 680 lines markdown

1---2title: Fallback credit3url: https://platform.claude.com/docs/en/build-with-claude/fallback-credit4description: Avoid paying the prompt-cache cost twice when you retry a refused request on another model.5---67Prompt caches are per-model. When a model declines a request and you retry on another model, the conversation prefix already cached for the first model must be written into the new model's cache from scratch. Cache writes cost more than cache reads. Fallback credit removes that extra cost. The refusal carries a credit token, you echo the token on the retry, and the retry is billed as though the conversation had been on the new model all along.89You need this page only when you build the retry yourself: over raw HTTP or with custom retry logic. [Server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback) and the [SDK middleware](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#client-side-fallback) apply fallback credit automatically. If you use either, skip this page.1011[Refusals and fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback) covers detecting refusals and choosing a fallback approach. [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) explains cache reads and cache writes if those terms are new.1213## The basic flow1415<Steps>16  <Step title="Opt in with the beta header">17    Send the request that may be refused with the `anthropic-beta: fallback-credit-2026-07-01` header. The `server-side-fallback-2026-07-01` header also grants the same fields, and the earlier `fallback-credit-2026-06-01` header remains accepted and grants the same fields.18  </Step>1920  <Step title="Read two fields from the refusal">21    On a refusal, `stop_details` includes two fields:2223    * **`fallback_credit_token`:** an opaque string that represents the credit.24    * **`fallback_has_prefill_claim`:** a Boolean that tells you which retry body shape to use.2526    Both are `null` when no credit is available for the refusal.27  </Step>2829  <Step title="Build the retry">30    Start from the refused request body. Set `model` to the fallback model and add the token as the top-level `fallback_credit_token` parameter. Pick the body shape from the following table.31  </Step>3233  <Step title="Send the retry with the same header">34    Send the retry with the same `fallback-credit-2026-07-01` beta header. The retry needs the header to redeem the token.35  </Step>36</Steps>3738The `fallback_has_prefill_claim` field tells you whether the retry can continue the refused model's partial output instead of starting over:3940| `fallback_has_prefill_claim` | Retry body                                                                                                                                                                                                                                                          |41| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |42| `true`                       | The refused request body, unchanged, plus one appended assistant message whose `content` echoes the refused response's `content`. The retry model continues the response from where the refused model stopped, and completed server tool calls are not re-executed. |43| `false`                      | The refused request body, unchanged.                                                                                                                                                                                                                                |4445## Example4647The following example makes a request that may be refused and redeems the credit token on a retry against Claude Opus 4.8. When a retry attempt is rejected, the example degrades through the rejection ladder: the sequence of progressively simpler retry shapes covered in [When a retry is rejected](https://platform.claude.com/docs/en/build-with-claude/fallback-credit#when-a-retry-is-rejected).4849<CodeGroup>50  ```bash cURL51  # Initial request (may be refused)52  response=$(curl --fail-with-body -sS https://api.anthropic.com/v1/messages \53    -H "x-api-key: $ANTHROPIC_API_KEY" \54    -H "anthropic-version: 2023-06-01" \55    -H "anthropic-beta: fallback-credit-2026-07-01" \56    -H "content-type: application/json" \57    -d '{58      "model": "claude-fable-5",59      "max_tokens": 1024,60      "messages": [{"role": "user", "content": "Hello, Claude"}]61    }')6263  # A refusal carries a one-time credit token in stop_details64  token=$(jq -r '.stop_details.fallback_credit_token // empty' <<<"${response}")6566  if [[ -n "${token}" ]]; then67    # Retry on the fallback model with the credit token (same body)68    response=$(curl --fail-with-body -sS https://api.anthropic.com/v1/messages \69      -H "x-api-key: $ANTHROPIC_API_KEY" \70      -H "anthropic-version: 2023-06-01" \71      -H "anthropic-beta: fallback-credit-2026-07-01" \72      -H "content-type: application/json" \73      -d "$(jq -n --arg token "${token}" '{74        model: "claude-opus-4-8",75        max_tokens: 1024,76        messages: [{"role": "user", "content": "Hello, Claude"}],77        fallback_credit_token: $token78      }')")79  fi8081  # See the SDK examples for the full rejection-handling ladder.82  jq -c '{stop_reason, model}' <<<"${response}"83  ```8485  ```bash CLI86  # Initial request (may be refused)87  response=$(ant beta:messages create \88    --model claude-fable-5 \89    --max-tokens 1024 \90    --message '{"role":"user","content":"Hello, Claude"}' \91    --beta fallback-credit-2026-07-01 \92    --format json)9394  # A refusal carries a one-time credit token in stop_details95  token=$(jq -r '.stop_details.fallback_credit_token // empty' <<<"${response}")9697  if [[ -n "${token}" ]]; then98    # Retry on the fallback model with the credit token99    response=$(ant beta:messages create \100      --model claude-opus-4-8 \101      --max-tokens 1024 \102      --message '{"role":"user","content":"Hello, Claude"}' \103      --fallback-credit-token "${token}" \104      --beta fallback-credit-2026-07-01 \105      --format json)106  fi107108  # See the SDK examples for the full rejection-handling ladder.109  jq -c '{stop_reason, model}' <<<"${response}"110  ```111112  ```python Python113  client = Anthropic()114115  request = {116      "max_tokens": 1024,117      "messages": [{"role": "user", "content": "Hello, Claude"}],118  }119120121  def send(model: str, body: dict[str, object]) -> BetaMessage:122      return client.beta.messages.create(123          model=model, betas=["fallback-credit-2026-07-01"], **body124      )125126127  response = send("claude-fable-5", request)128129  if (130      response.stop_reason == "refusal"131      and (details := response.stop_details)132      and (token := details.fallback_credit_token)133  ):134      exact_body = request | {"fallback_credit_token": token}135      # Prefer the continuation shape unless the claim is False136      if details.fallback_has_prefill_claim is not False:137          echoed = [block.model_dump() for block in response.content]138          match echoed:139              case [*_, {"type": "text"} as final_block]:140                  final_block["text"] = final_block["text"].rstrip()141          attempt = exact_body | {142              "messages": [143                  *request["messages"],144                  {"role": "assistant", "content": echoed},145              ]146          }147      else:148          attempt = exact_body149150      try:151          response = send("claude-opus-4-8", attempt)152      except BadRequestError as error:153          if "redemption temporarily unavailable" in error.message:154              raise  # Transient: retry with the token within its five-minute window155          try:156              # Fall back to the unchanged body, still with the token157              response = send("claude-opus-4-8", exact_body)158          except BadRequestError as retry_error:159              if "redemption temporarily unavailable" in retry_error.message:160                  raise  # Transient: retry with the token within its five-minute window161              # The token itself was rejected: forfeit it and retry without.162              response = send("claude-opus-4-8", request)163164  print(json.dumps({"stop_reason": response.stop_reason, "model": response.model}))165  ```166167  ```typescript TypeScript168  const client = new Anthropic();169170  const request: Anthropic.Beta.MessageCreateParamsNonStreaming = {171    model: "claude-fable-5",172    max_tokens: 1024,173    messages: [{ role: "user", content: "Hello, Claude" }],174    betas: ["fallback-credit-2026-07-01"]175  };176177  let response = await client.beta.messages.create(request);178179  if (180    response.stop_reason === "refusal" &&181    response.stop_details?.type === "refusal" &&182    response.stop_details.fallback_credit_token183  ) {184    const { fallback_credit_token, fallback_has_prefill_claim } = response.stop_details;185    const fallbackModel = "claude-opus-4-8";186187    const exactRetry: Anthropic.Beta.MessageCreateParamsNonStreaming = {188      ...request,189      model: fallbackModel,190      fallback_credit_token191    };192193    // Richest shape first, degrading on each rejection: the continuation194    // shape (unless the claim is false), the unchanged body still carrying195    // the token, and finally forfeiting the token.196    let attempt = exactRetry;197    if (fallback_has_prefill_claim !== false) {198      const finalBlock = response.content.at(-1);199      const echoed: Anthropic.Beta.BetaContentBlockParam[] =200        finalBlock?.type === "text"201          ? [202              ...response.content.slice(0, -1),203              { ...finalBlock, text: finalBlock.text.trimEnd() }204            ]205          : response.content;206      attempt = {207        ...exactRetry,208        messages: [...request.messages, { role: "assistant", content: echoed }]209      };210    }211212    try {213      response = await client.beta.messages.create(attempt);214    } catch (error) {215      // Degrade only on a shape-related 400. "redemption temporarily216      // unavailable" is transient: retry the same way within the token's217      // five-minute window instead.218      if (219        !(error instanceof Anthropic.BadRequestError) ||220        error.message.includes("redemption temporarily unavailable")221      ) {222        throw error;223      }224      try {225        response = await client.beta.messages.create(exactRetry);226      } catch (retryError) {227        if (228          !(retryError instanceof Anthropic.BadRequestError) ||229          retryError.message.includes("redemption temporarily unavailable")230        ) {231          throw retryError;232        }233        response = await client.beta.messages.create({ ...request, model: fallbackModel });234      }235    }236  }237238  const { stop_reason, model } = response;239  console.log(JSON.stringify({ stop_reason, model }));240  ```241242  ```csharp C#243  var client = new AnthropicClient();244  const string beta = "fallback-credit-2026-07-01";245246  List<BetaMessageParam> requestMessages =247  [248      new() { Role = Role.User, Content = "Hello, Claude" },249  ];250  MessageCreateParams Request(string model) => new()251  {252      Model = model,253      MaxTokens = 1024,254      Messages = requestMessages,255      Betas = [beta],256  };257  var response = await client.Beta.Messages.Create(Request("claude-fable-5"));258259  if (260      response.StopReason == BetaStopReason.Refusal261      && response.StopDetails is { FallbackCreditToken: string token } details262  )263  {264      var exactBody = Request("claude-opus-4-8") with { FallbackCreditToken = token };265      var attempt = exactBody;266      // Prefer the continuation shape unless the claim is false267      if (details.FallbackHasPrefillClaim is not false)268      {269          var echoed = JsonArray.Create(response.RawData["content"])!;270          if (271              echoed is [.., JsonObject lastBlock]272              && lastBlock["type"]?.GetValue<string>() is "text"273              && lastBlock["text"]?.GetValue<string>() is string text274          )275          {276              lastBlock["text"] = text.TrimEnd();277          }278          attempt = exactBody with279          {280              Messages =281              [282                  .. requestMessages,283                  new()284                  {285                      Role = Role.Assistant,286                      Content = new BetaMessageParamContent(287                          JsonSerializer.SerializeToElement(echoed)288                      ),289                  },290              ],291          };292      }293      // A transient "redemption temporarily unavailable" rejection propagates out of294      // each of the following catch filters: retry with the token within its five-minute window.295      try296      {297          response = await client.Beta.Messages.Create(attempt);298      }299      catch (AnthropicBadRequestException e)300          when (!e.Message.Contains("redemption temporarily unavailable"))301      {302          try303          {304              // Fall back to the unchanged body, still with the token305              response = await client.Beta.Messages.Create(exactBody);306          }307          catch (AnthropicBadRequestException retryError)308              when (!retryError.Message.Contains("redemption temporarily unavailable"))309          {310              // The token itself was rejected: forfeit it and retry without.311              response = await client.Beta.Messages.Create(Request("claude-opus-4-8"));312          }313      }314  }315316  Console.WriteLine(317      JsonSerializer.Serialize(318          new { stop_reason = response.StopReason?.Raw(), model = response.Model.Raw() }319      )320  );321  ```322323  ```go Go324  ctx := context.Background()325  client := anthropic.NewClient()326327  request := anthropic.BetaMessageNewParams{328  	MaxTokens: 1024,329  	Betas:     []anthropic.AnthropicBeta{anthropic.AnthropicBetaFallbackCredit2026_07_01},330  	Messages: []anthropic.BetaMessageParam{331  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude")),332  	},333  }334335  send := func(model anthropic.Model, body anthropic.BetaMessageNewParams) (*anthropic.BetaMessage, error) {336  	body.Model = model337  	return client.Beta.Messages.New(ctx, body)338  }339  // A non-transient 400 means this attempt shape or token was rejected and340  // the next rung of the ladder should run. "redemption temporarily341  // unavailable" is transient: surface it and retry with the token within342  // its five-minute window.343  canFallBack := func(err error) bool {344  	apiErr, ok := errors.AsType[*anthropic.Error](err)345  	return ok && apiErr.StatusCode == 400 &&346  		!strings.Contains(apiErr.Error(), "redemption temporarily unavailable")347  }348349  response, err := send(anthropic.ModelClaudeFable5, request)350  if err != nil {351  	log.Fatal(err)352  }353354  if response.StopReason == anthropic.BetaStopReasonRefusal {355  	details := response.StopDetails356  	if token := details.FallbackCreditToken; token != "" {357  		exactBody := request358  		exactBody.FallbackCreditToken = anthropic.BetaMessageNewParamsFallbackCreditTokenUnion{359  			OfString: anthropic.String(token),360  		}361  		attempt := exactBody362  		// Prefer the continuation shape unless the claim is false363  		if details.FallbackHasPrefillClaim || !details.JSON.FallbackHasPrefillClaim.Valid() {364  			echoed := response.ToParam()365  			if len(echoed.Content) > 0 {366  				if text := echoed.Content[len(echoed.Content)-1].OfText; text != nil {367  					text.Text = strings.TrimRightFunc(text.Text, unicode.IsSpace)368  				}369  			}370  			attempt.Messages = append(slices.Clone(request.Messages), echoed)371  		}372  		response, err = send(anthropic.ModelClaudeOpus4_8, attempt)373  		if err != nil && canFallBack(err) {374  			// Fall back to the unchanged body, still with the token375  			response, err = send(anthropic.ModelClaudeOpus4_8, exactBody)376  			if err != nil && canFallBack(err) {377  				// The token itself was rejected: forfeit it and retry without.378  				response, err = send(anthropic.ModelClaudeOpus4_8, request)379  			}380  		}381  		if err != nil {382  			log.Fatal(err)383  		}384  	}385  }386387  summary, err := json.Marshal(struct {388  	StopReason anthropic.BetaStopReason `json:"stop_reason"`389  	Model      anthropic.Model          `json:"model"`390  }{response.StopReason, response.Model})391  if err != nil {392  	log.Fatal(err)393  }394  fmt.Println(string(summary))395  ```396397  ```java Java398  AnthropicClient client = AnthropicOkHttpClient.fromEnv();399400  MessageCreateParams.Builder request() {401      return MessageCreateParams.builder()402          .maxTokens(1024L)403          .addUserMessage("Hello, Claude")404          .addBeta(AnthropicBeta.FALLBACK_CREDIT_2026_07_01);405  }406407  BetaMessage send(Model model, MessageCreateParams.Builder body) {408      return client.beta().messages().create(body.model(model).build());409  }410411  void main() {412      BetaMessage response = send(Model.CLAUDE_FABLE_5, request());413414      if (response.stopReason().map(BetaStopReason.REFUSAL::equals).orElse(false)415              && response.stopDetails().orElse(null) instanceof BetaRefusalStopDetails details416              && details.fallbackCreditToken().orElse(null) instanceof String creditToken) {417          MessageCreateParams.Builder attempt = request().fallbackCreditToken(creditToken);418          // Prefer the continuation shape unless the claim is false419          if (details.fallbackHasPrefillClaim().orElse(true)) {420              List<BetaContentBlockParam> echoed = new ArrayList<>(421                  response.content().stream().map(BetaContentBlock::toParam).toList());422              if (!echoed.isEmpty() && echoed.getLast().isText()) {423                  var lastText = echoed.removeLast().asText();424                  echoed.addLast(BetaContentBlockParam.ofText(425                      lastText.toBuilder().text(lastText.text().stripTrailing()).build()));426              }427              attempt.addAssistantMessageOfBetaContentBlockParams(echoed);428          }429          try {430              response = send(Model.CLAUDE_OPUS_4_8, attempt);431          } catch (BadRequestException badRequest) {432              // Transient: retry with the token within its five-minute window433              if (badRequest.getMessage().contains("redemption temporarily unavailable")) {434                  throw badRequest;435              }436              try {437                  // Fall back to the unchanged body, still with the token438                  response = send(Model.CLAUDE_OPUS_4_8, request().fallbackCreditToken(creditToken));439              } catch (BadRequestException retryBadRequest) {440                  if (retryBadRequest.getMessage().contains("redemption temporarily unavailable")) {441                      throw retryBadRequest;442                  }443                  // The token itself was rejected: forfeit it and retry without.444                  response = send(Model.CLAUDE_OPUS_4_8, request());445              }446          }447      }448449      IO.println("""450          {"stop_reason": "%s", "model": "%s"}"""451          .formatted(response.stopReason().orElseThrow(), response.model()));452  }453  ```454455  ```php PHP456  $client = new Client();457  $beta = 'fallback-credit-2026-07-01';458  $messages = [['role' => 'user', 'content' => 'Hello, Claude']];459460  $send = fn (string $model, array $messages, ?string $token = null) => $client->beta->messages->create(461      maxTokens: 1024,462      messages: $messages,463      model: $model,464      fallbackCreditToken: $token,465      betas: [$beta],466  );467  $response = $send('claude-fable-5', $messages);468469  $token = $response->stopReason === 'refusal'470      ? $response->stopDetails?->fallbackCreditToken471      : null;472473  if ($token !== null) {474      $attemptMessages = $messages;475      // Prefer the continuation shape unless the claim is false476      if ($response->stopDetails->fallbackHasPrefillClaim !== false) {477          $echoed = $response->content478              |> json_encode(...)479              |> (fn (string $json): array => json_decode($json, associative: true));480          $lastIndex = array_key_last($echoed);481          if ($lastIndex !== null && $echoed[$lastIndex]['type'] === 'text') {482              $echoed[$lastIndex]['text'] = rtrim($echoed[$lastIndex]['text']);483          }484          $attemptMessages[] = ['role' => 'assistant', 'content' => $echoed];485      }486      // Transient: retry with the token within its five-minute window487      $isTransientRedemption = fn (BadRequestException $error): bool =>488          str_contains($error->getMessage(), 'redemption temporarily unavailable');489      try {490          $response = $send('claude-opus-4-8', $attemptMessages, $token);491      } catch (BadRequestException $error) {492          if ($isTransientRedemption($error)) {493              throw $error;494          }495          try {496              // Fall back to the unchanged body, still with the token497              $response = $send('claude-opus-4-8', $messages, $token);498          } catch (BadRequestException $retryError) {499              if ($isTransientRedemption($retryError)) {500                  throw $retryError;501              }502              // The token itself was rejected: forfeit it and retry without.503              $response = $send('claude-opus-4-8', $messages);504          }505      }506  }507508  echo json_encode(['stop_reason' => $response->stopReason, 'model' => $response->model]), PHP_EOL;509  ```510511  ```ruby Ruby512  client = Anthropic::Client.new513514  request = {515    max_tokens: 1024,516    messages: [{role: "user", content: "Hello, Claude"}]517  }518519  send_message = ->(model, body) do520    client.beta.messages.create(model:, betas: ["fallback-credit-2026-07-01"], **body)521  end522523  response = send_message.call("claude-fable-5", request)524525  if response in {stop_reason: :refusal,526                  stop_details: {fallback_credit_token: String => credit_token} => details}527    exact_body = request.merge(fallback_credit_token: credit_token)528529    # Prefer the continuation shape unless the claim is false530    attempt = if details.fallback_has_prefill_claim != false531      echoed = response.content.map(&:to_h)532      if echoed.last in {type: :text, text: String => final_text}533        echoed[-1] = echoed.last.merge(text: final_text.rstrip)534      end535      exact_body.merge(536        messages: [*request[:messages], {role: "assistant", content: echoed}]537      )538    else539      exact_body540    end541542    begin543      response = send_message.call("claude-opus-4-8", attempt)544    rescue Anthropic::Errors::BadRequestError => error545      # Transient: retry with the token within its five-minute window546      raise if error.message.include?("redemption temporarily unavailable")547      begin548        # Fall back to the unchanged body, still with the token549        response = send_message.call("claude-opus-4-8", exact_body)550      rescue Anthropic::Errors::BadRequestError => error551        # Transient: retry with the token within its five-minute window552        raise if error.message.include?("redemption temporarily unavailable")553        # The token itself was rejected: forfeit it and retry without.554        response = send_message.call("claude-opus-4-8", request)555      end556    end557  end558559  puts JSON.generate({stop_reason: response.stop_reason, model: response.model})560  ```561</CodeGroup>562563## Where it works564565Fallback credit is in beta on the Claude API, Amazon Bedrock, Claude Platform on AWS, Google Cloud, and Microsoft Foundry. Refusals in [Message Batches](https://platform.claude.com/docs/en/build-with-claude/batch-processing) don't mint credit tokens, and redemption applies only to direct Messages API requests: a token passed on a batch request is accepted but ignored.566567The retry model must be one of the refused model's permitted fallback targets. For Claude Fable 5.1 and Claude Fable 5, those are Claude Opus 4.8 (`claude-opus-4-8`) and Claude Opus 5 (`claude-opus-5`).568569<Accordion title="Looking up permitted fallback targets programmatically">570  On the Claude API and Claude Platform on AWS, the target list is published as `allowed_fallback_models` on each model's entry in the [Models API](https://platform.claude.com/docs/en/api/models/list) when the `server-side-fallback-2026-07-01` beta header is set. The list is not yet visible under the `fallback-credit-*` header alone. It is not exposed on Amazon Bedrock, Google Cloud, or Microsoft Foundry.571</Accordion>572573## Checking that the credit applied574575The refund is visible in the retry's `usage`. Compared with what the same request would report without the token, `cache_creation_input_tokens` is lower, and `cache_read_input_tokens` is higher by the same amount. A shift of zero means the token was honored but there was nothing to reprice, for example because the retry model's cache was already warm.576577## When a retry is rejected578579Most retries redeem on the first attempt. When one does not, the API returns a 400 error that tells you what to try next.580581<Steps>582  <Step title="Continuation rejected: resend the unchanged body">583    If the retry that appends the assistant message is rejected with a 400 error, resend the refused request body unchanged, still with the token.584  </Step>585586  <Step title="Token rejected: drop the token">587    If the unchanged body is also rejected with a 400 error whose message names `fallback_credit_token`, retry without the token. The credit is forfeited, but the retry itself goes through.588  </Step>589</Steps>590591<Note>592  If the refused request executed server tools, a tokenless retry re-runs and re-bills those tools. In that case, surface the 400 error to your caller instead of falling through to a tokenless retry.593</Note>594595<Accordion title="If the error says 'redemption temporarily unavailable'">596  This rejection is transient, not a verdict on your retry shape. Retry the same request, with the same token, within the token's five-minute window. Do not move to the next step of the ladder.597</Accordion>598599## Reference600601The following sections cover edge cases and the complete redemption rules. Most integrations do not need them.602603<Accordion title="Fields that must match the refused request">604  Redemption compares the retry against the refused request. Every field that shapes the prompt must match exactly. Fields that do not shape the prompt may change on the retry.605606  | Rule                    | Fields                                                                                                                                                                      |607  | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |608  | Must match exactly      | `system`, `messages`, `tools`, `tool_choice`, `thinking`, and `cache_control`, plus `output_config`, `mcp_servers`, `context_management`, and `container` when you use them |609  | May change on the retry | `model`, `max_tokens`, `stop_sequences`, `temperature`, `top_p`, `top_k`, `stream`, `metadata`, and `service_tier`                                                          |610611  The continuation shape (`fallback_has_prefill_claim: true`) is the one exception to the `messages` match: it adds exactly one assistant message at the end of `messages`.612613  Do not strip `thinking` or `redacted_thinking` blocks from earlier turns on the retry, even though a plain retry without a token usually strips them. The body must match the refused request, and the server handles those blocks itself.614</Accordion>615616<Accordion title="Beta headers must match too">617  Send the same `anthropic-beta` headers on the retry as on the refused request. A beta header present on one of the two requests but not the other can fail the match even when the bodies are identical. The resulting 400 error carries the same `request body ... does not match` message as a body difference, so a header difference is easy to misread as a body problem. In particular, do not add or drop beta headers based on which model the request targets.618619  Two header families are exempt from the match, for the retry's sake:620621  * **`server-side-fallback-*`:** a retry must drop the `fallbacks` parameter, and dropping this header along with it does not cause a mismatch.622  * **`fallback-credit-*`:** keep this header on both requests. The retry needs it to redeem the token.623624  <Note>625    On models that include the 1M token context window by default, such as Claude Fable 5.1, Claude Fable 5, Claude Opus 5, and Claude Opus 4.8, the `context-1m-2025-08-07` beta header has no effect. To keep the two requests identical, omit that header on both rather than sending it on one and not the other.626  </Note>627</Accordion>628629<Accordion title="When fallback_has_prefill_claim is absent">630  The field is `null` only when the token is also `null`, so a value you observe while holding a token is never `null`. It can still be absent (`None` in the typed SDKs) on Amazon Bedrock, Google Cloud, and Microsoft Foundry while their support for the field rolls out. In that case, treat the retry shape as unknown rather than as `false`. Try the appended-assistant-message shape first, and rely on the rejection handling in [When a retry is rejected](https://platform.claude.com/docs/en/build-with-claude/fallback-credit#when-a-retry-is-rejected), which falls back to the unchanged body.631</Accordion>632633<Accordion title="Echoing the refused response's content">634  When a refusal's token supports the continuation shape, the response `content` carries only the model's own output, and the refusal explanation is delivered in `stop_details.explanation`. You can therefore echo `content` into the appended assistant message as-is.635636  Two adjustments may still be needed before sending:637638  * If the final block you send is a `text` block, strip its trailing whitespace.639  * Omit any client-side `tool_use` block that has no matching `tool_result`.640641  If the echoed content includes a `fallback` block from an earlier [server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback), keep the block exactly where it appeared. It is accepted on any request without a beta header. The API uses its position to validate the thinking blocks around it, so a request that echoes thinking blocks from both sides of that boundary is rejected if the block is omitted or moved.642</Accordion>643644<Accordion title="Token scope and lifetime">645  The token redeems only from the organization and workspace that received the refusal, including on Microsoft Foundry. On Amazon Bedrock and Google Cloud, which do not have workspaces, the token is bound to the platform's caller identity instead.646647  The token expires five minutes after the refusal. After that, send the retry without it. The token is also stateless: the server stores nothing about it, and there is no endpoint to inspect or revoke it.648</Accordion>649650<Accordion title="When a token cannot be redeemed by either shape">651  When the refusal arrived after server tools had already executed within the request, the token redeems only by continuing the partial response. That restriction is what prevents the completed tool calls from running, and billing, again.652653  One combination can therefore leave the token unredeemable by either shape, when both of the following are true:654655  * The request used `output_config.format` or a `tool_choice` that forces tool use. Either one rules out the appended-assistant-message shape.656  * The refusal arrived after server tools had executed. That rules out the unchanged body.657658  If the unchanged-body retry is rejected with a 400 error saying the token must be redeemed by continuing the partial response, discard the token. A retry without it goes through, but it re-runs and re-bills the completed server tools. Surface the cost or the error to your caller rather than retrying silently.659</Accordion>660661## Next steps662663<CardGroup>664  <Card title="Refusals and fallback" icon="shield" href="https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback">665    Detect refusals and choose between server-side fallback, the SDK middleware, and a manual retry.666  </Card>667668  <Card title="Prompt caching" icon="bolt" href="https://platform.claude.com/docs/en/build-with-claude/prompt-caching">669    How cache reads and cache writes are billed.670  </Card>671672  <Card title="Stop reasons and fallback" icon="code" href="https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons">673    Every `stop_reason` value and how to handle it.674  </Card>675676  <Card title="SDK middleware" icon="settings" href="https://platform.claude.com/docs/en/cli-sdks-libraries/middleware">677    The SDK helper that applies fallback credit automatically.678  </Card>679</CardGroup>680
Files main
Menu

Theme