Fallback-Gutschrift
Vermeide es, die Prompt-Cache-Kosten doppelt zu bezahlen, wenn du eine abgelehnte Anfrage auf einem anderen Modell wiederholst.
Prompt-Caches gelten pro Modell. Wenn ein Modell eine Anfrage ablehnt und du sie auf einem anderen Modell wiederholst, muss das für das erste Modell bereits gecachte Gesprächspräfix von Grund auf in den Cache des neuen Modells geschrieben werden. Cache-Schreibvorgänge kosten mehr als Cache-Lesevorgänge. „Fallback credit“ (Fallback-Gutschrift) beseitigt diese zusätzlichen Kosten. Die Ablehnung enthält ein Gutschrift-Token, du gibst das Token bei der Wiederholung zurück, und die Wiederholung wird so abgerechnet, als wäre das Gespräch von Anfang an auf dem neuen Modell geführt worden.
Du brauchst diese Seite nur, wenn du die Wiederholung selbst baust: über reines HTTP oder mit eigener Wiederholungslogik. Serverseitiger Fallback und die SDK-Middleware wenden die Fallback-Gutschrift 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 dir diese Begriffe neu sind.
Der grundlegende Ablauf
Mit dem Beta-Header aktivieren
Sende die Anfrage, die möglicherweise abgelehnt wird, mit dem Header
anthropic-beta: fallback-credit-2026-07-01. Der Headerserver-side-fallback-2026-07-01gewährt ebenfalls dieselben Felder, und der frühere Headerfallback-credit-2026-06-01wird weiterhin akzeptiert und gewährt dieselben Felder.Zwei Felder aus der Ablehnung lesen
Bei einer Ablehnung enthält
stop_detailszwei Felder:fallback_credit_token: eine opake Zeichenkette, die die Gutschrift repräsentiert.fallback_has_prefill_claim: ein Boolean, der dir sagt, welche Form des Wiederholungs-Bodys du verwenden sollst.
Beide sind
null, wenn für die Ablehnung keine Gutschrift verfügbar ist.Die Wiederholung erstellen
Beginne mit dem Body der abgelehnten Anfrage. Setze
modelauf das Fallback-Modell und füge das Token als Top-Level-Parameterfallback_credit_tokenhinzu. Wähle die Body-Form aus der folgenden Tabelle.Die Wiederholung mit demselben Header senden
Sende die Wiederholung mit demselben Beta-Header
fallback-credit-2026-07-01. Die Wiederholung benötigt den Header, um das Token einzulösen.
Das Feld fallback_has_prefill_claim sagt dir, ob die Wiederholung die Teilausgabe des ablehnenden Modells fortsetzen kann, anstatt von vorne zu beginnen:
fallback_has_prefill_claim | Wiederholungs-Body |
|---|---|
true | Der Body der abgelehnten Anfrage, unverändert, plus eine angehängte Assistant-Nachricht, deren content den content der abgelehnten Antwort wiedergibt. Das Wiederholungsmodell setzt die Antwort dort fort, wo das ablehnende Modell aufgehört hat, und abgeschlossene Server-Tool-Aufrufe werden nicht erneut ausgeführt. |
false | Der Body der abgelehnten Anfrage, unverändert. |
Beispiel
Das folgende Beispiel stellt eine Anfrage, die möglicherweise abgelehnt wird, und löst das Gutschrift-Token bei einer Wiederholung gegen Claude Opus 4.8 ein. Wenn ein Wiederholungsversuch zurückgewiesen wird, stuft das Beispiel über die Zurückweisungsleiter herab: die Abfolge zunehmend einfacherer Wiederholungsformen, die in Wenn eine Wiederholung 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, außer der Claim ist False
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:
# Falle 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: verwirf es 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
Die Fallback-Gutschrift befindet sich in der Beta auf der Claude API, Amazon Bedrock, Claude Platform auf AWS, Google Cloud und Microsoft Foundry. Ablehnungen in Message Batches erzeugen keine Gutschrift-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 Wiederholungsmodell muss eines der zulässigen Fallback-Ziele des ablehnenden Modells sein. Für Claude Fable 5.1 und Claude Fable 5 sind das Claude Opus 4.8 (claude-opus-4-8) und Claude Opus 5 (claude-opus-5).
Auf der Claude API und Claude Platform auf AWS wird die Zielliste als allowed_fallback_models im Eintrag jedes Modells in der Models API veröffentlicht, wenn der Beta-Header server-side-fallback-2026-07-01 gesetzt ist. Die Liste ist unter dem Header fallback-credit-* allein noch nicht sichtbar. Sie wird auf Amazon Bedrock, Google Cloud oder Microsoft Foundry nicht bereitgestellt.
Prüfen, ob die Gutschrift angewendet wurde
Die Erstattung ist in der 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 anerkannt wurde, es aber nichts neu zu bepreisen gab, zum Beispiel weil der Cache des Wiederholungsmodells bereits warm war.
Wenn eine Wiederholung zurückgewiesen wird
Die meisten Wiederholungen werden beim ersten Versuch eingelöst. Wenn das nicht der Fall ist, gibt die API einen 400-Fehler zurück, der dir sagt, was du als Nächstes versuchen sollst.
Fortsetzung zurückgewiesen: den unveränderten Body erneut senden
Wenn die Wiederholung, die die Assistant-Nachricht anhängt, mit einem 400-Fehler zurückgewiesen wird, sende den Body der abgelehnten Anfrage unverändert erneut, weiterhin mit dem Token.
Token zurückgewiesen: das Token weglassen
Wenn auch der unveränderte Body mit einem 400-Fehler zurückgewiesen wird, dessen Meldung
fallback_credit_tokennennt, wiederhole ohne das Token. Die Gutschrift verfällt, aber die Wiederholung selbst geht durch.
Diese Zurückweisung ist vorübergehend und kein Urteil über deine Wiederholungsform. Wiederhole dieselbe Anfrage mit demselben Token innerhalb des Fünf-Minuten-Fensters des Tokens. Gehe nicht zur nächsten Stufe der Leiter über.
Referenz
Die folgenden Abschnitte behandeln Grenzfälle und die vollständigen Einlösungsregeln. Die meisten Integrationen benötigen sie nicht.
Die Einlösung vergleicht die Wiederholung mit der abgelehnten Anfrage. Jedes Feld, das den Prompt formt, muss exakt übereinstimmen. Felder, die den Prompt nicht formen, dürfen sich bei der Wiederholung ändern.
| Regel | Felder |
|---|---|
| Muss exakt übereinstimmen | system, messages, tools, tool_choice, thinking und cache_control, plus output_config, mcp_servers, context_management und container, wenn du sie verwendest |
| Darf sich bei der Wiederholung ändern | model, max_tokens, stop_sequences, temperature, top_p, top_k, stream, metadata und service_tier |
Die Fortsetzungsform (fallback_has_prefill_claim: true) ist die einzige Ausnahme von der messages-Übereinstimmung: Sie fügt genau eine Assistant-Nachricht am Ende von messages hinzu.
Entferne bei der Wiederholung keine thinking- oder redacted_thinking-Blöcke aus früheren Turns, auch wenn eine einfache Wiederholung ohne Token sie normalerweise entfernt. Der Body muss mit der abgelehnten Anfrage übereinstimmen, und der Server behandelt diese Blöcke selbst.
Sende bei der Wiederholung dieselben anthropic-beta-Header wie bei der abgelehnten Anfrage. Ein Beta-Header, der bei einer der beiden Anfragen vorhanden ist, bei der anderen aber nicht, kann die Übereinstimmung scheitern lassen, selbst wenn die Bodys identisch sind. Der resultierende 400-Fehler trägt dieselbe Meldung request body ... does not match wie ein Body-Unterschied, sodass ein Header-Unterschied leicht als Body-Problem missverstanden wird. Füge insbesondere keine Beta-Header hinzu und lasse keine weg, je nachdem, auf welches Modell die Anfrage abzielt.
Zwei Header-Familien sind zugunsten der Wiederholung von der Übereinstimmung ausgenommen:
server-side-fallback-*: Eine Wiederholung muss den Parameterfallbacksweglassen, und das Weglassen dieses Headers zusammen damit verursacht keine Nichtübereinstimmung.fallback-credit-*: Behalte diesen Header bei beiden Anfragen. Die Wiederholung benötigt ihn, um das Token einzulösen.
Das Feld ist nur dann null, wenn auch das Token null ist, sodass ein Wert, den du beobachtest, während du ein Token hältst, niemals null ist. Es kann auf Amazon Bedrock, Google Cloud und Microsoft Foundry dennoch fehlen (None in den typisierten SDKs), während deren Unterstützung für das Feld ausgerollt wird. Behandle in diesem Fall die Wiederholungsform als unbekannt statt als false. Versuche zuerst die Form mit angehängter Assistant-Nachricht und verlasse dich auf die Zurückweisungsbehandlung in Wenn eine Wiederholung zurückgewiesen wird, die auf den unveränderten Body zurückfällt.
Wenn das Token einer Ablehnung die Fortsetzungsform unterstützt, enthält der content der Antwort nur die eigene Ausgabe des Modells, und die Erklärung der Ablehnung wird in stop_details.explanation geliefert. Du kannst content daher unverändert in die angehängte Assistant-Nachricht übernehmen.
Zwei Anpassungen können vor dem Senden dennoch nötig sein:
- Wenn der letzte Block, den du sendest, ein
text-Block ist, entferne dessen nachgestellten Leerraum. - Lasse jeden clientseitigen
tool_use-Block weg, der kein passendestool_resulthat.
Wenn der wiedergegebene Inhalt einen fallback-Block aus einem früheren serverseitigen Fallback enthält, behalte den Block genau dort, wo er erschien. Er wird bei jeder Anfrage ohne Beta-Header akzeptiert. Die API verwendet seine Position, um die Thinking-Blöcke um ihn herum zu validieren, sodass eine Anfrage, die Thinking-Blöcke von beiden Seiten dieser Grenze wiedergibt, zurückgewiesen wird, wenn der Block weggelassen oder verschoben wird.
Das Token lässt sich nur von der Organisation und dem Workspace einlösen, die die Ablehnung erhalten haben, auch auf Microsoft Foundry. Auf Amazon Bedrock und Google Cloud, die keine Workspaces haben, ist das Token stattdessen an die Aufruferidentität der Plattform gebunden.
Das Token läuft fünf Minuten nach der Ablehnung ab. Sende die Wiederholung danach ohne es. Das Token ist außerdem zustandslos: Der Server speichert nichts darüber, und es gibt keinen Endpunkt, um es zu inspizieren oder zu widerrufen.
Wenn die Ablehnung eintraf, nachdem innerhalb der Anfrage bereits Server-Tools ausgeführt worden waren, lässt sich das Token nur durch Fortsetzen der Teilantwort einlösen. Diese Einschränkung verhindert, dass die abgeschlossenen Tool-Aufrufe erneut ausgeführt und abgerechnet werden.
Eine Kombination kann das Token daher mit keiner der beiden Formen einlösbar machen, wenn beides Folgende zutrifft:
- Die Anfrage verwendete
output_config.formatoder eintool_choice, das Tool-Nutzung erzwingt. Beides schließt die Form mit angehängter Assistant-Nachricht aus. - Die Ablehnung traf ein, nachdem Server-Tools ausgeführt worden waren. Das schließt den unveränderten Body aus.
Wenn die Wiederholung mit unverändertem Body mit einem 400-Fehler zurückgewiesen wird, der besagt, dass das Token durch Fortsetzen der Teilantwort eingelöst werden muss, verwirf das Token. Eine Wiederholung ohne es geht durch, führt aber die abgeschlossenen Server-Tools erneut aus und rechnet sie erneut ab. Gib die Kosten oder den Fehler an deinen Aufrufer weiter, anstatt stillschweigend zu wiederholen.
Nächste Schritte
Erkenne Ablehnungen und wähle zwischen serverseitigem Fallback, der SDK-Middleware und einer manuellen Wiederholung.
Wie Cache-Lesevorgänge und Cache-Schreibvorgänge abgerechnet werden.
Jeder stop_reason-Wert und wie du damit umgehst.
Der SDK-Helfer, der die Fallback-Gutschrift automatisch anwendet.
Was this page helpful?