Repository Public
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