Fallback-Guthaben

Prompt-Caches sind modellspezifisch. Wenn Claude Fable 5 eine Anfrage ablehnt und du sie auf einem anderen Modell wiederholst, muss das Konversationspräfix, das bereits für Claude Fable 5 gecacht war, von Grund auf in den Cache des neuen Modells geschrieben werden. Cache-Schreibvorgänge kosten mehr als Cache-Lesevorgänge. Das „fallback credit" (Fallback-Guthaben) beseitigt diese zusätzlichen Kosten. Die Ablehnung enthält ein Guthaben-Token, du gibst das Token bei der Wiederholung zurück, und die Wiederholung wird so abgerechnet, als wäre die Konversation von Anfang an auf dem neuen Modell gewesen.

Du brauchst diese Seite nur, wenn du die Wiederholung selbst implementierst: mit dem Ruby- oder PHP-SDK, über rohes HTTP oder mit eigener Retry-Logik. Server-seitiger Fallback und die SDK-Middleware wenden das Fallback-Guthaben automatisch an. Wenn du eines von beiden verwendest, überspringe diese Seite.

Ablehnungen und Fallback behandelt das Erkennen von Ablehnungen und die Wahl eines Fallback-Ansatzes. Prompt-Caching erklärt Cache-Lesevorgänge und Cache-Schreibvorgänge, falls diese Begriffe neu für dich sind.



Der grundlegende Ablauf

Das Feld fallback_has_prefill_claim sagt dir, ob die Wiederholung die Teilausgabe des abgelehnten Modells fortsetzen kann, anstatt von vorne zu beginnen:



Beispiel

Das folgende Beispiel stellt eine Anfrage, die möglicherweise abgelehnt wird, und löst das Guthaben-Token bei einer Wiederholung gegen Claude Opus 4.8 ein. Wenn ein Wiederholungsversuch abgelehnt wird, durchläuft das Beispiel die Ablehnungsleiter: die Abfolge zunehmend einfacherer Retry-Formen, die in Wenn eine Wiederholung abgelehnt wird behandelt wird.

client = Anthropic()

request = {
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude"}],
}


def send(model, body):
    return client.beta.messages.create(
        model=model, betas=["fallback-credit-2026-06-01"], **body
    )


response = send("claude-fable-5", request)

if (
    response.stop_reason == "refusal"
    and (details := response.stop_details)
    and (token := details.fallback_credit_token)
):
    exact_body = request | {"fallback_credit_token": token}
    # Bevorzuge die Fortsetzungsform, außer die Behauptung ist False
    if details.fallback_has_prefill_claim is not False:
        # Gib den Inhalt der Ablehnung zurück, entferne nachgestellte Leerzeichen aus einem
        # abschließenden Textblock (der Prefill-Validator lehnt sie ab; der serverseitige
        # Abgleich toleriert die Änderung). Anfragen mit Tool-Nutzung lassen zudem ungepaarte
        # tool_use-Blöcke weg und entfernen nach den Auslassungen erneut Leerzeichen.
        echoed = [block.model_dump() for block in response.content]
        match echoed:
            case [*_, {"type": "text"} as final_block]:
                final_block["text"] = final_block["text"].rstrip()
        attempt = exact_body | {
            "messages": [
                *request["messages"],
                {"role": "assistant", "content": echoed},
            ]
        }
    else:
        attempt = exact_body

    try:
        response = send("claude-opus-4-8", attempt)
    except BadRequestError as error:
        if "redemption temporarily unavailable" in str(error):
            raise  # Transient: retry with the token within its five-minute window
        try:
            # Greife auf den unveränderten Body zurück, weiterhin mit dem Token
            response = send("claude-opus-4-8", exact_body)
        except BadRequestError as error:
            if "redemption temporarily unavailable" in str(error):
                raise  # Transient: retry with the token within its five-minute window
            # Das Token selbst wurde abgelehnt: gib es auf und versuche es ohne erneut.
            response = send("claude-opus-4-8", request)

print(json.dumps({"stop_reason": response.stop_reason, "model": response.model}))



Wo es funktioniert

Fallback-Guthaben ist in der Beta-Phase auf der Claude API, Claude Platform on AWS, Amazon Bedrock, Google Cloud und Microsoft Foundry verfügbar. Guthaben-Token, die in Message Batches-Ergebnissen zurückgegeben werden, können nicht eingelöst werden. Die Einlösung gilt nur für direkte Messages-API-Anfragen.

Das Retry-Modell muss eines der zulässigen Fallback-Ziele des abgelehnten Modells sein. Zum Start ist das zulässige Ziel von Claude Fable 5 Claude Opus 4.8 (claude-opus-4-8).



Überprüfen, ob das Guthaben angewendet wurde

Die Erstattung ist im usage der Wiederholung sichtbar. Verglichen mit dem, was dieselbe Anfrage ohne das Token melden würde, ist cache_creation_input_tokens niedriger und cache_read_input_tokens um denselben Betrag höher. Eine Verschiebung von null bedeutet, dass das Token akzeptiert wurde, aber nichts neu zu bepreisen war, zum Beispiel weil der Cache des Retry-Modells bereits warm war.



Wenn eine Wiederholung abgelehnt wird

Die meisten Wiederholungen werden beim ersten Versuch eingelöst. Wenn nicht, gibt die API einen 400-Fehler zurück, der dir sagt, was du als Nächstes versuchen sollst.



Referenz

Die folgenden Abschnitte behandeln Sonderfälle und die vollständigen Einlösungsregeln. Die meisten Integrationen benötigen sie nicht.



Nächste Schritte