Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

Fallback credit for refused requests (beta)

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.

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 returns the same refusal fields. On Amazon Bedrock, a retry redeemed under fallback-credit-2026-06-01 doesn't report usage.fallback_credit. Use fallback-credit-2026-07-01 for new code. The server-side-fallback-2026-07-01 flag is not supported on Amazon Bedrock and returns a 400 error.

Supported models

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.

Refusals from other models, including 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.

A refusal from a source model doesn't always carry a token. When no credit is available for the refusal, fallback_credit_token and fallback_has_prefill_claim are both null. Check for a token before you build a redeeming retry.

Supported endpoints

Fallback credit works on both of the following endpoints. Where you pass the beta flag depends on the endpoint.

Fallback credit is available on each endpoint that the source model supports.

With Converse, a refusal returns stopReason: "content_filtered". To get the token, add "/stop_details" to additionalModelResponseFieldPaths, and pass fallback_credit_token on the retry in additionalModelRequestFields. Converse doesn't report usage.fallback_credit. To confirm that the credit applied, check that cacheReadInputTokens covers the conversation prefix and cacheWriteInputTokens doesn't.

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.

How it works

Step 1: Receive a fallback credit token on refusal

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:

{
  "id": "msg_bdrk_...",
  "type": "message",
  "role": "assistant",
  "model": "anthropic.claude-opus-5-5",
  "content": [],
  "stop_reason": "refusal",
  "stop_details": {
    "type": "refusal",
    "category": "cyber",
    "explanation": "This request triggered restrictions on violative cyber content and was blocked under Anthropic's Usage Policy.",
    "fallback_credit_token": "<opaque token>",
    "fallback_has_prefill_claim": false
  },
  "usage": {
    "input_tokens": 12,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 42029,
    "output_tokens": 1
  }
}

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.

Step 2: Redeem the token on a retry request

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:

{
  "anthropic_version": "bedrock-2023-05-31",
  "anthropic_beta": ["fallback-credit-2026-07-01"],
  "max_tokens": 4096,
  "system": "...",
  "messages": [...],
  "tools": [...],
  "fallback_credit_token": "<token from the refusal's stop_details>"
}

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>"
  }'

Redemption rules

Error handling

With the beta flag present, a redemption validation failure returns a 400 error. Failure conditions include:

When a retry is rejected, step down through progressively simpler retries:

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.

Without the beta flag, fallback_credit_token is rejected as an unknown field (400). The parameter is also rejected on CountTokens requests.

Billing impact

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:

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.

Fallback credit reduces only the cost of the retry. The refused request itself is billed by its stop_details.category: before any output, bio, frontier_llm, and reasoning_extraction refusals are billed, and cyber, general_harms, and null refusals aren't. Amazon Bedrock always bills a mid-stream refusal. For details, see Billing notes.

A reasoning_extraction refusal has no recommended fallback model. Change the prompt instead of retrying on another model.

Limitations

Example workflow

The following Python example implements this workflow with InvokeModel, including the retry steps described in Error handling.

import json
import time

import boto3
from botocore.exceptions import ClientError

client = boto3.client("bedrock-runtime", region_name="us-east-1")

SOURCE_MODEL = "global.anthropic.claude-opus-5-5"
FALLBACK_MODEL = "global.anthropic.claude-opus-5"

request = {
    "anthropic_version": "bedrock-2023-05-31",
    "anthropic_beta": ["fallback-credit-2026-07-01"],
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "<long system prompt>",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    "messages": [{"role": "user", "content": "Hello, Claude"}],
}


def invoke(model_id, body):
    response = client.invoke_model(modelId=model_id, body=json.dumps(body))
    return json.loads(response["body"].read())


def invoke_with_transient_retry(model_id, body, tries=3):
    # "redemption temporarily unavailable" is transient: resend the same body,
    # with the same token, within the 5-minute window.
    for attempt in range(tries):
        try:
            return invoke(model_id, body)
        except ClientError as error:
            transient = "redemption temporarily unavailable" in error.response["Error"]["Message"]
            if not transient or attempt == tries - 1:
                raise
            time.sleep(2 ** attempt)


def can_step_down(error, forfeit_next):
    message = error.response["Error"]["Message"]
    if error.response["Error"]["Code"] != "ValidationException":
        return False
    if "redemption temporarily unavailable" in message:
        return False  # Still transient after retries: surface it, keep the token
    # Drop the token only when the error names it.
    return not forfeit_next or "fallback_credit_token" in message


result = invoke(SOURCE_MODEL, request)
details = result.get("stop_details") or {}
token = details.get("fallback_credit_token")

if result["stop_reason"] == "refusal" and token:
    exact_body = {**request, "fallback_credit_token": token}
    attempts = []

    # Prefer the continuation shape unless the claim is explicitly false.
    if details.get("fallback_has_prefill_claim") is not False and result["content"]:
        # Omit client tool_use blocks: they have no matching tool_result.
        echoed = [block for block in result["content"] if block["type"] != "tool_use"]
        if echoed and echoed[-1]["type"] == "text":
            echoed[-1]["text"] = echoed[-1]["text"].rstrip()
        attempts.append(
            {**exact_body, "messages": [*request["messages"], {"role": "assistant", "content": echoed}]}
        )

    attempts.append(exact_body)  # Unchanged body, still with the token
    attempts.append(request)     # Last resort: forfeit the credit

    for body in attempts:
        try:
            result = invoke_with_transient_retry(FALLBACK_MODEL, body)
            break
        except ClientError as error:
            forfeit_next = attempts.index(body) == len(attempts) - 2
            if body is request or not can_step_down(error, forfeit_next):
                raise

print(json.dumps({"stop_reason": result["stop_reason"], "usage": result["usage"]}, indent=2))

If the token is null, expired, or rejected, retry without it. The credit is a cost optimization; the retry doesn't need it to succeed.