AWS bedrock: Expand Bedrock Claude fallback credit docs (new beta flag, endpoints, retry rules)
Summary
Rewrites the Claude Messages fallback credit guide: replaces beta flag fallback-credit-2026-06-01 with fallback-credit-2026-07-01, adds a supported source/fallback model table, a new 'Supported endpoints' section (bedrock-runtime vs bedrock-mantle and where to pass the beta flag), new stop_details fields (fallback_credit_token, fallback_has_prefill_claim), expanded redemption rules (caller binding, matching fields, retry shapes), error-handling step-down guidance, billing/usage repricing details, a Limitations section, and a Python retry example.
Security assessment
The change is a billing/cost-optimization documentation update for the fallback credit token (cache-write vs cache-read repricing, beta flag rename, endpoint and retry-shape rules). The only access-control-flavored statement is the caller-binding rule for redeeming a credit token, which is an anti-abuse/billing constraint rather than a fix for a vulnerability, CVE, or incident; no credential, encryption, IAM, or exposure change is described.
Evidence
+**Caller binding** | The token can only be redeemed by the same caller identity that received the refusal, on the same endpoint. Tokens are stateless; there is no API to inspect or revoke them.
Diff
diff --git a/bedrock/latest/userguide/claude-messages-fallback-credit.md b/bedrock/latest/userguide/claude-messages-fallback-credit.md index a858ddf..75fb21d 100644 --- a//bedrock/latest/userguide/claude-messages-fallback-credit.md +++ b//bedrock/latest/userguide/claude-messages-fallback-credit.md @@ -7 +7 @@ -Supported modelsHow it worksRedemption rulesError handlingBilling impactExample workflow +Supported modelsSupported endpointsHow it worksRedemption rulesError handlingBilling impactLimitationsExample workflow @@ -11 +11 @@ Supported modelsHow it worksRedemption rulesError handlingBilling impactExample -When Claude Fable 5 refuses a request, customers who retry the same conversation on a different model (such as Claude Opus 4.8) normally re-pay cache-write rates for the conversation prefix that was already cached on Fable 5. Fallback credit eliminates this double-charge by issuing a one-time credit token on refusal that can be redeemed on the retry. +Prompt caches are per model. When a Claude model refuses a request and you retry the same conversation on a different model, the conversation prefix that was already cached for the first model is written into the new model's cache in full, at cache-write rates. Fallback credit removes this extra cost. The refusal carries a one-time credit token. When you include the token on the retry, the retry is billed as though the conversation had been on the fallback model from the start: the overlapping prefix is billed as cache-read tokens instead of cache-write tokens. @@ -13 +13 @@ When Claude Fable 5 refuses a request, customers who retry the same conversation -This feature requires the beta flag `fallback-credit-2026-06-01` in the `anthropic_beta` array on both the original request and the retry. +To use fallback credit, include the beta flag `fallback-credit-2026-07-01` on both the original request and the retry. The earlier flag `fallback-credit-2026-06-01` is still accepted and behaves the same way. The `server-side-fallback-2026-07-01` flag is not supported on Amazon Bedrock and returns a `400` error. @@ -17 +17,16 @@ This feature requires the beta flag `fallback-credit-2026-06-01` in the `anthrop -**Role** | **Model** +The following models issue a fallback credit token when they refuse a request. The retry must use one of the listed fallback models for that source model. You can use the base model ID or a cross-Region inference profile ID (for example, `global.anthropic.claude-opus-5-5`) for either request. + +**Source model (issues the token)** | **Model ID** | **Valid fallback models (redeem the token)** +---|---|--- +Claude Fable 5 | `anthropic.claude-fable-5` | Claude Opus 4.8 (`anthropic.claude-opus-4-8`) +Claude Opus 5.5 | `anthropic.claude-opus-5-5` | Claude Opus 5 (`anthropic.claude-opus-5`), Claude Opus 4.8 (`anthropic.claude-opus-4-8`) +Claude Opus 5 | `anthropic.claude-opus-5` | Claude Opus 4.8 (`anthropic.claude-opus-4-8`) +Claude Sonnet 5.5 | `anthropic.claude-sonnet-5-5` | Claude Sonnet 5 (`anthropic.claude-sonnet-5`) + +Refusals from other models, including Claude Fable 5.1, Claude Mythos 5.1, and Claude Haiku 5.5, don't carry a fallback credit token. A retry after one of those refusals pays the full cost of writing the fallback model's prompt cache. + +## Supported endpoints + +Fallback credit works on both of the following endpoints. Where you pass the beta flag depends on the endpoint. + +**Endpoint** | **How to pass the beta flag** @@ -19,2 +34,6 @@ This feature requires the beta flag `fallback-credit-2026-06-01` in the `anthrop -Source (issues credit on refusal) | Claude Fable 5 -Target (redeems credit on retry) | Must be a valid fallback target of the source model +`bedrock-runtime` (`InvokeModel`, `InvokeModelWithResponseStream`) | In the `anthropic_beta` array of the request body. +`bedrock-mantle` (`/anthropic/v1/messages`) | In the `anthropic-beta` HTTP header, or the `betas` parameter of the Anthropic SDK. + +Fallback credit is available on each endpoint that the source model supports. + +Redeem the token on the same endpoint that issued it. A token minted on `bedrock-mantle` can only be redeemed on `bedrock-mantle`, and a token minted on `bedrock-runtime` can only be redeemed on `bedrock-runtime`. A token sent to the other endpoint is rejected with a `request body ... does not match` error. @@ -26 +45,8 @@ Target (redeems credit on retry) | Must be a valid fallback target of the source -When a request to Claude Fable 5 returns `stop_reason: "refusal"` and the beta flag is present, the `stop_details` object includes a `fallback_credit_token`: +When a request to a supported source model returns `stop_reason: "refusal"` and the beta flag is present, the `stop_details` object includes two fields: + + * `fallback_credit_token` – An opaque string that represents the credit. + + * `fallback_has_prefill_claim` – A boolean that tells you which retry body shape to use. For more information, see Redemption rules. + + + @@ -30 +56 @@ When a request to Claude Fable 5 returns `stop_reason: "refusal"` and the beta f - "id": "msg_...", + "id": "msg_bdrk_...", @@ -33 +59 @@ When a request to Claude Fable 5 returns `stop_reason: "refusal"` and the beta f - "model": "anthropic.claude-fable-5", + "model": "anthropic.claude-opus-5-5", @@ -40 +66,2 @@ When a request to Claude Fable 5 returns `stop_reason: "refusal"` and the beta f - "fallback_credit_token": "<opaque token>" + "fallback_credit_token": "<opaque token>", + "fallback_has_prefill_claim": false @@ -43 +70,3 @@ When a request to Claude Fable 5 returns `stop_reason: "refusal"` and the beta f - "input_tokens": 106, + "input_tokens": 12, + "cache_creation_input_tokens": 0, + "cache_read_input_tokens": 42029, @@ -48 +77,3 @@ When a request to Claude Fable 5 returns `stop_reason: "refusal"` and the beta f -The `fallback_credit_token` is an opaque string. It is `null` when mint conditions are not met (no cache was read on the original request, model is not credit-eligible, or beta flag is absent). Server-side minting failures produce `null`, never an error. +Both fields are `null` when no credit is available for the refusal, for example when no cache was read on the refused request, the model isn't a supported source model, or the beta flag is absent. Server-side minting failures produce `null`, never an error. In streaming mode, the fields are delivered in the `stop_details` of the final `message_delta` event. + +Because a token requires a cache read, a refusal on the first request of a conversation, which only writes the cache, doesn't carry a token. A later refused request that reads the cached prefix does. @@ -50 +81,3 @@ The `fallback_credit_token` is an opaque string. It is `null` when mint conditio -In streaming mode, the token is delivered in the final `message_delta` event's `stop_details`. +###### Note + +On Amazon Bedrock, `fallback_has_prefill_claim` can be absent even when a token is present. If it's absent, treat the retry shape as unknown rather than as `false`: try the continuation shape first, and fall back to the unchanged body if the retry is rejected. For more information, see Error handling. @@ -54 +87,3 @@ In streaming mode, the token is delivered in the final `message_delta` event's ` -Pass the token as a top-level parameter on the retry to the fallback model: +Start from the refused request body. Change `model` (or the model ID in the request path) to a valid fallback model, keep the same beta flag, and add the token as the top-level `fallback_credit_token` parameter. Send the retry within 5 minutes of the refusal. + +The following example shows a retry body for `InvokeModel` with the model ID `global.anthropic.claude-opus-5`: @@ -59,2 +94 @@ Pass the token as a top-level parameter on the retry to the fallback model: - "anthropic_beta": ["fallback-credit-2026-06-01"], - "model": "anthropic.claude-opus-4-8", + "anthropic_beta": ["fallback-credit-2026-07-01"], @@ -67,0 +102,17 @@ Pass the token as a top-level parameter on the retry to the fallback model: +The following example shows the same retry on `bedrock-mantle`: + + + curl -X POST "https://bedrock-mantle.$BEDROCK_REGION.api.aws/anthropic/v1/messages" \ + -H "x-api-key: $BEDROCK_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -H "anthropic-beta: fallback-credit-2026-07-01" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "anthropic.claude-opus-5", + "max_tokens": 4096, + "system": "...", + "messages": [...], + "tools": [...], + "fallback_credit_token": "<token from the refusal's stop_details>" + }' + @@ -72,5 +123,12 @@ Pass the token as a top-level parameter on the retry to the fallback model: -**Time window** | Token must be redeemed within 5 minutes of being issued. -**Platform binding** | A token minted on `bedrock-mantle` can only be redeemed on `bedrock-mantle`. -**Body match** | The `system`, `messages`, and `tools` fields must match the refused request exactly. Send them as-is; do not strip thinking blocks. -**Retry shapes** | The retry body must either (a) match the refused request exactly (the fallback model regenerates the response), or (b) match it with one appended assistant message containing the refused response's partial output (the fallback model continues from where Fable 5 was interrupted). -**Target model** | Must be a valid fallback target of the refused model. +**Time window** | The token expires 5 minutes after the refusal. After that, send the retry without it. +**Caller binding** | The token can only be redeemed by the same caller identity that received the refusal, on the same endpoint. Tokens are stateless; there is no API to inspect or revoke them. +**Target model** | The retry must use a valid fallback model for the refused model. See Supported models. +**Fields that must match** | `system`, `messages`, `tools`, `tool_choice`, `thinking`, and `cache_control`, plus `output_config`, `mcp_servers`, `context_management`, and `container` if you use them. Send them as-is. Don't strip `thinking` or `redacted_thinking` blocks from earlier turns. +**Fields that can change** | `model`, `max_tokens`, `stop_sequences`, `stream`, `metadata`, and `service_tier`. +**Beta flags** | Send the same beta flags on the retry as on the refused request. A flag that is present on only one of the two requests causes a `request body ... does not match` error, even if the bodies are identical. Don't add or drop flags based on the target model. +**Retry shape** | Choose the retry body based on `fallback_has_prefill_claim`: + + * `true` – The refused request body, unchanged, plus one appended `assistant` message whose `content` echoes the refused response's `content`. The fallback model continues the response from where the refused model stopped. Strip trailing whitespace from a final `text` block, and omit any client `tool_use` block that has no matching `tool_result`. + * `false` – The refused request body, unchanged. The fallback model regenerates the response. + + @@ -80 +138 @@ Pass the token as a top-level parameter on the retry to the fallback model: -With the beta flag present, any redemption validation failure returns a `400 invalid_request_error`. The recovery path in every case is to retry without `fallback_credit_token`. Failure conditions include: +With the beta flag present, a redemption validation failure returns a `400` error. Failure conditions include: @@ -86 +144 @@ With the beta flag present, any redemption validation failure returns a `400 inv - * Request body does not match the original refused request + * Request body or beta flags don't match the refused request @@ -88 +146 @@ With the beta flag present, any redemption validation failure returns a `400 inv - * Target model is not a valid fallback target + * Target model isn't a valid fallback model for the refused model @@ -95 +153,16 @@ With the beta flag present, any redemption validation failure returns a `400 inv -Without the beta flag, `fallback_credit_token` is rejected as an unknown field (400). The parameter is also rejected on `count_tokens` requests. +When a retry is rejected, step down through progressively simpler retries: + + 1. If the continuation retry (with the appended `assistant` message) is rejected, resend the refused request body unchanged, still with the token. + + 2. If the unchanged body is also rejected with an error that names `fallback_credit_token`, retry without the token. The credit is forfeited, but the retry goes through. + + + + +If the error message says `redemption temporarily unavailable`, the rejection is transient. Retry the same request with the same token within the 5-minute window instead of stepping down. + +###### Important + +If the refused request ran server tools, a retry without the token runs those tools again and bills them again. In that case, surface the error to your caller instead of silently retrying without the token. + +Without the beta flag, `fallback_credit_token` is rejected as an unknown field (`400`). The parameter is also rejected on `CountTokens` requests. @@ -99 +172,36 @@ Without the beta flag, `fallback_credit_token` is rejected as an unknown field ( -When a fallback credit token is successfully redeemed, the retry request receives a credit for cache-write tokens that overlap with the refused request's cached prefix. The customer pays only for net-new tokens on the retry, not for re-caching the conversation prefix. +When a token is redeemed, the credit is applied by repricing the retry's token usage. There is no separate credit or refund line item. Compared with the same retry without a token, the retry's `usage` reports fewer `cache_creation_input_tokens` and more `cache_read_input_tokens` by the same amount. Your bill, cost and usage reports, and the `CacheWriteInputTokenCount` and `CacheReadInputTokenCount` metrics in CloudWatch reflect the repriced counts. + +The following example shows the retry's usage for a conversation with a 42,000-token cached prefix that was refused by Claude Opus 5.5 and retried on Claude Opus 5: + +**Retry** | **`usage.fallback_credit`** | **`cache_creation_input_tokens`** | **`cache_read_input_tokens`** +---|---|---|--- +Without `fallback_credit_token` | – | 42,029 | 0 +With `fallback_credit_token` | `{"status": {"type": "redeemed"}}` | 0 | 42,033 + +A successfully redeemed retry also reports the redemption in `usage.fallback_credit`: + + + "usage": { + "input_tokens": 45, + "cache_creation_input_tokens": 0, + "cache_read_input_tokens": 42033, + "fallback_credit": { + "status": {"type": "redeemed"} + }, + "output_tokens": 512 + } + +If a redeemed retry shows no shift, the token was honored but there was nothing to reprice, for example because the fallback model's cache was already warm. + +## Limitations + + * Refusals in batch inference jobs don't issue tokens. A token passed in a batch inference record is accepted but ignored. + + * Amazon Bedrock doesn't expose the `allowed_fallback_models` list. Use the table in Supported models. + + * Server-side fallback (the `fallbacks` parameter and the `server-side-fallback-2026-07-01` flag) isn't supported on Amazon Bedrock. You build the retry yourself. + + * If the request used `output_config.format` or a `tool_choice` that forces tool use, and the refusal arrived after server tools had run, the token can't be redeemed by either retry shape. Retry without the token. + + + @@ -103 +211 @@ When a fallback credit token is successfully redeemed, the retry request receive - 1. Send a request to Claude Fable 5 with `anthropic_beta: ["fallback-credit-2026-06-01"]`. + 1. Send a request to Claude Opus 5.5 with `"anthropic_beta": ["fallback-credit-2026-07-01"]` and a cached prompt prefix. @@ -107 +215,55 @@ When a fallback credit token is successfully redeemed, the retry request receive - 3. Immediately retry to Claude Opus 4.8 with the same `system`, `messages`, and `tools`, plus the `fallback_credit_token`. + 3. Within 5 minutes, retry on Claude Opus 5 with the same body and beta flags, plus the `fallback_credit_token`. + + 4. Check the retry's `usage`: the overlapping prefix is billed as cache-read tokens instead of cache-write tokens. + + + + +The following Python example implements this workflow with `InvokeModel`, including the retry steps described in Error handling. + +