Fallback-Credit

Prompt-Caches sind modellspezifisch. Wenn Claude Fable 5 eine Anfrage ablehnt und du sie auf einem anderen Modell erneut versuchst, muss das Gesprächspräfix, das bereits für Claude Fable 5 gecacht war, von Grund auf neu in den Cache des neuen Modells geschrieben werden. Cache-Schreibvorgänge kosten mehr als Cache-Lesevorgänge. Fallback-Credit beseitigt diese zusätzlichen Kosten. Die Ablehnung enthält ein Credit-Token, du gibst das Token beim erneuten Versuch zurück, und der erneute Versuch wird so abgerechnet, als wäre das Gespräch von Anfang an auf dem neuen Modell gewesen.

Du brauchst diese Seite nur, wenn du den erneuten Versuch selbst baust: über rohes HTTP oder mit eigener Retry-Logik. Server-seitiger Fallback und die SDK-Middleware wenden Fallback-Credit 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 der erneute Versuch die partielle Ausgabe des abgelehnten Modells fortsetzen kann, anstatt von vorne zu beginnen:



Beispiel

Das folgende Beispiel stellt eine Anfrage, die abgelehnt werden könnte, und löst das Credit-Token bei einem erneuten Versuch gegen Claude Opus 4.8 ein. Wenn ein Retry-Versuch zurückgewiesen wird, arbeitet sich das Beispiel durch die Zurückweisungsleiter: die Abfolge zunehmend einfacherer Retry-Formen, die in Wenn ein erneuter Versuch zurückgewiesen wird behandelt wird.

client = Anthropic()

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


def send(model: str, body: dict[str, object]) -> BetaMessage:
    return client.beta.messages.create(
        model=model, betas=["fallback-credit-2026-07-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, sofern die Behauptung nicht False ist
    if details.fallback_has_prefill_claim is not False:
        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 error.message:
            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 retry_error:
            if "redemption temporarily unavailable" in retry_error.message:
                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-Credit ist in der Beta auf der Claude API, Amazon Bedrock, Claude Platform auf AWS, Google Cloud und Microsoft Foundry verfügbar. Ablehnungen in Message Batches erzeugen keine Credit-Tokens, und die Einlösung gilt nur für direkte Messages-API-Anfragen: Ein Token, das bei einer Batch-Anfrage übergeben wird, wird akzeptiert, aber ignoriert.

Das Retry-Modell muss eines der zulässigen Fallback-Ziele des abgelehnten Modells sein. Die zulässigen Ziele von Claude Fable 5 sind Claude Opus 4.8 (claude-opus-4-8) und Claude Opus 5 (claude-opus-5).



Prüfen, ob das Guthaben angewendet wurde

Die Rückerstattung ist in der usage des erneuten Versuchs 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 berücksichtigt wurde, aber nichts neu zu bepreisen war, zum Beispiel weil der Cache des Retry-Modells bereits warm war.



Wenn ein erneuter Versuch zurückgewiesen wird

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



Referenz

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



Nächste Schritte