Ablehnungen und Fallback

Claude Fable 5 und Claude Opus 5 enthalten Sicherheitsklassifizierer, die eine Anfrage ablehnen können. Wenn das passiert, erhältst du eine normale Antwort, keinen Fehler, mit stop_reason: "refusal". Du kannst in der Regel trotzdem eine Antwort bekommen, indem du dieselbe Anfrage an ein anderes Claude-Modell sendest. Diese Seite zeigt dir, wie du eine „refusal" (Ablehnung) erkennst und wie du diesen Wiederholungsversuch einrichtest.

Lies diese Seite, wenn du auf Claude Fable 5 oder Claude Opus 5 aufbaust und möchtest, dass abgelehnte Anfragen automatisch an ein anderes Modell weitergereicht werden. Sie gilt auch, wenn du gerade "refusal" in einer Antwort gesehen hast und wissen möchtest, was als Nächstes zu tun ist.

Verwandte Seiten:

• Stop-Gründe und Fallback: die vollständige Liste der stop_reason-Werte.
• Fallback-Guthaben: wie abgelehnte Anfragen abgerechnet werden und wie du vermeidest, bei einem Wiederholungsversuch zweimal für Prompt-Caching zu bezahlen.
• SDK-Middleware: der SDK-Helfer, der all das kapselt.
• Fallback- und Abrechnungs-Cookbook: ein durchgearbeitetes End-to-End-Beispiel.

Die einfachste Einrichtung, in der Beta auf der Claude API: Setze fallbacks auf "default", und die API wiederholt eine abgelehnte Anfrage auf dem Fallback-Modell, das Anthropic für ihre Ablehnungskategorie empfiehlt. Für Kategorien ohne empfohlenes Fallback bleibt die Ablehnung bestehen.

client = Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    fallbacks="default",
    betas=["server-side-fallback-2026-07-01"],
)
print(response.model)

Die folgenden Abschnitte behandeln, was eine Ablehnungsantwort enthält, wann du serverseitiges oder clientseitiges Fallback verwenden solltest und wie jedes abgerechnet wird.



Wie eine Ablehnung aussieht

Eine Ablehnung ist eine erfolgreiche HTTP-200-Antwort mit stop_reason: "refusal":

{
  "id": "msg_01XFUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-fable-5",
  "content": [],
  "stop_reason": "refusal",
  "stop_details": {
    "type": "refusal",
    "category": "cyber",
    "explanation": "This request was declined because it could enable cyber harm."
  },
  "usage": {
    "input_tokens": 412,
    "output_tokens": 0
  }
}

Das stop_details-Objekt erklärt die Ablehnung:

• category: benennt den Richtlinienbereich, der den Klassifizierer ausgelöst hat.
• explanation: eine menschenlesbare Beschreibung. Der Text ist nicht stabil, zeige ihn also an, anstatt ihn zu parsen.
• Beide Felder sind null, wenn die Ablehnung keiner benannten Kategorie zugeordnet werden kann. Dieses null ist ein normaler, dauerhafter Wert, kein Platzhalter.
• stop_details selbst ist null für jeden Stop-Grund außer refusal.

Eine Ablehnung kann vor jeglicher Ausgabe eintreffen oder mitten im Stream nach teilweiser Ausgabe. Behandle in beiden Fällen jede teilweise Ausgabe als unvollständig und verwirf sie.



Einen Fallback-Ansatz wählen

Es gibt drei Möglichkeiten, eine abgelehnte Anfrage auf einem anderen Modell zu wiederholen. Die richtige hängt davon ab, wo du läufst und wie viel Kontrolle du brauchst.

Serverseitiges Fallback und die SDK-Middleware wenden Fallback-Guthaben für dich an. Du brauchst die Seite Fallback-Guthaben nur, wenn du den Wiederholungsversuch selbst baust.



Serverseitiges Fallback

Serverseitiges Fallback wiederholt eine abgelehnte Anfrage innerhalb eines einzigen API-Aufrufs. Im Standardmodus führt die API, wenn das primäre Modell ablehnt und die Ablehnungskategorie ein empfohlenes Fallback hat, dieselbe Anfrage auf dem Modell aus, das Anthropic für diese Kategorie empfiehlt. Du kannst stattdessen bis zu drei eigene Fallback-Modelle benennen (siehe unten). In beiden Fällen erhältst du eine Antwort zurück, die das Modell benennt, das geantwortet hat, sodass dein Nutzer in einem einzigen Roundtrip eine Antwort bekommt.



Die Anfrage stellen

Setze den fallbacks-Parameter auf den String "default" und sende den Beta-Header server-side-fallback-2026-07-01. Die API wendet dann das serverdefinierte Standard-Routing des angeforderten Modells an, das ein empfohlenes Fallback-Modell basierend auf der vom Klassifizierer gemeldeten Ablehnungskategorie auswählt, sodass abgelehnte Anfragen bedient werden, ohne dass du eine Modellliste pflegen musst, wenn sich Empfehlungen ändern.

client = Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    fallbacks="default",
    betas=["server-side-fallback-2026-07-01"],
)

# Ein fallback_message-Eintrag in usage.iterations bedeutet, dass ein Fallback-Modell lief;
# kombiniere ihn mit stop_reason, um zu bestätigen, dass der Fallback die Antwort geliefert hat.
fallback_ran = any(
    iteration.type == "fallback_message"
    for iteration in response.usage.iterations or []
)
served_by_fallback = fallback_ran and response.stop_reason != "refusal"

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

Anthropic legt Schutzmaßnahmen für jedes Modell einzeln und für jede Richtlinienkategorie fest, entsprechend der Fähigkeit des Modells: Je nach Kategorie kann eine markierte Anfrage auf ein weniger leistungsfähiges Modell zurückfallen oder abgelehnt werden. Der "default"-Modus kodiert diese Empfehlungen pro Modell und pro Kategorie für dich, sodass eine abgelehnte Anfrage auf dem Modell wiederholt wird, das Anthropic für diese Kategorie empfiehlt. Fallbacks sind in jedem Fall sichtbar: Die Antwort benennt das Modell, das sie bedient hat, und der fallback-Content-Block markiert die Übergabe.

Das Routing wird serverseitig angewendet und wird nicht pro Modell auf der Models API veröffentlicht. Um zu sehen, welches Modell eine abgelehnte Anfrage bedient hat, prüfe das model-Feld auf oberster Ebene der Antwort und suche nach einem fallback_message-Eintrag in usage.iterations, wie es die Beispiele auf dieser Seite tun.

Nur eine Ablehnung durch den Sicherheitsklassifizierer löst das Fallback aus. Ein Ratenlimit, eine Überlastung oder ein Serverfehler auf dem angeforderten Modell wird dir unverändert zurückgegeben.



Eigene Fallback-Modelle benennen

Anstelle des Standard-Routings kannst du fallbacks auf eine Liste von bis zu drei Modellen setzen. Wenn das angeforderte Modell ablehnt, führt die API das nächste Modell in der Kette auf derselben Anfrage aus. Verwende diese Form, wenn du genau kontrollieren möchtest, welche Modelle abgelehnte Anfragen bedienen, etwa um ein Modell festzulegen, das deine Anwendung qualifiziert hat.

client = Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    fallbacks=[{"model": "claude-opus-4-8"}],
    betas=["server-side-fallback-2026-07-01"],
)
print(response.model)

Für die fallbacks-Liste gelten einige Regeln:

• Einträge werden der Reihe nach ausprobiert. Jeder muss sich von den anderen Einträgen und vom angeforderten Modell unterscheiden.
• Jeder Eintrag muss eines der zulässigen Ziele des angeforderten Modells sein. Mit gesetztem Beta-Header wird diese Liste als allowed_fallback_models im Eintrag des Modells in der Models API veröffentlicht.
• Jeder Eintrag benennt ein model und kann max_tokens, thinking, output_config und speed nur für diesen Versuch überschreiben.
• Die Anfrage muss als direkte Anfrage an jedes benannte Modell gültig sein. Wenn ein Fallback-Modell ein Feature nicht unterstützt, das die Anfrage verwendet, lehnt die API die Anfrage von vornherein ab.
• Wie beim Standardmodus löst nur eine Ablehnung durch den Sicherheitsklassifizierer das Fallback aus. Ein Ratenlimit, eine Überlastung oder ein Serverfehler auf dem angeforderten Modell wird dir unverändert zurückgegeben.

Die explizite Listenform funktioniert auch unter dem Beta-Header server-side-fallback-2026-06-01; der "default"-Modus nicht.

Die Antwort hat in beiden Modi dieselbe Form: Das Modell, das den Turn bedient hat, erscheint im model-Feld auf oberster Ebene, ein fallback-Content-Block markiert die Übergabe, und usage.iterations zeichnet jeden Versuch auf.



Was die Antwort enthält

Die Antwort sieht aus wie jede andere Nachricht, mit zwei Ergänzungen:

• Das model-Feld auf oberster Ebene meldet das Modell, das die zurückgegebene Nachricht erzeugt hat, egal ob das das angeforderte Modell oder ein Fallback ist.
• Ein fallback-Content-Block markiert jeden Punkt in content, an dem die Ausgabe eines Modells an das nächste übergeht: {"type": "fallback", "from": {"model": ...}, "to": {"model": ...}}.
  • from.model gibt den Modell-String wieder, den du gesendet hast, wenn der ablehnende Hop das angeforderte Modell ist.
  • to.model ist immer die aufgelöste ID des Modells, das fortfährt.

Bei einer Ablehnung vor jeglicher Ausgabe ist der fallback-Block der erste Content-Block. Zum Beispiel, wenn das Standard-Routing Claude Opus 4.8 für die Kategorie der Ablehnung auswählt:

{
  "id": "msg_01XFUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-8",
  "content": [
    {
      "type": "fallback",
      "from": { "model": "claude-fable-5" },
      "to": { "model": "claude-opus-4-8" }
    },
    { "type": "text", "text": "Hi! How can I help you today?" }
  ],
  "stop_reason": "end_turn",
  "stop_details": null,
  "usage": {
    "input_tokens": 412,
    "output_tokens": 264,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "iterations": [
      {
        "type": "message",
        "model": "claude-fable-5",
        "input_tokens": 535,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0
      },
      {
        "type": "fallback_message",
        "model": "claude-opus-4-8",
        "input_tokens": 412,
        "output_tokens": 264,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0
      }
    ]
  }
}

Das usage.iterations-Array zeichnet jeden Versuch auf. Ein Modell, das abgelehnt hat, erscheint als gewöhnlicher message-Eintrag, und das Modell, das den Turn bedient hat, erscheint als fallback_message-Eintrag. Wenn jedes Modell in der Kette ablehnt, ist die Antwort die Ablehnung des letzten Modells, mit einem message-Eintrag für jeden früheren Hop und einem fallback_message-Eintrag für den letzten.



Das Gespräch fortsetzen

Sende im nächsten Turn den Assistant-Content so zurück, wie du ihn erhalten hast. Nach einem Fallback mitten in der Ausgabe kann content Blocktypen enthalten, die das ablehnende Modell vor der Übergabe erzeugt hat; die folgende Tabelle zeigt, welche du behalten und welche du weglassen solltest, wenn du den Turn zurücksendest.



Streaming

Bei einer Streaming-Anfrage erfolgt der Wiederholungsversuch auf demselben Stream, und nichts, was du bereits erhalten hast, wird ungültig. Was du siehst, hängt davon ab, wann die Ablehnung erfolgt.

Wenn die Ablehnung vor jeglicher Ausgabe erfolgt:

• message_start benennt das Fallback-Modell, und der fallback-Block ist der erste Content-Block.
• Da message_start auf den Start des Fallback-Versuchs wartet, schließt die Zeit bis zum ersten Byte den abgelehnten Versuch ein.

Wenn die Ablehnung mitten in der Ausgabe erfolgt:

• Der offene Content-Block wird geschlossen, und der fallback-Block (ein gewöhnliches content_block_start- und content_block_stop-Paar ohne Deltas) markiert die Grenze.
• Das Fallback-Modell setzt ab der teilweisen Ausgabe fort. Nur die text-Blöcke der teilweisen Ausgabe werden dem Fallback-Modell als Kontext übergeben; andere Blocktypen bleiben in content.
• message_start hat bereits das angeforderte Modell benannt, lies das bedienende Modell also aus dem to.model des fallback-Blocks und aus dem fallback_message-Eintrag in usage.iterations des letzten message_delta.



Nicht-Streaming-Antworten

Bei einer Nicht-Streaming-Anfrage verhält sich eine Ablehnung mitten in der Ausgabe anders: Die Antwort lässt die teilweise Ausgabe des abgelehnten Modells weg, und das Fallback-Modell antwortet von Grund auf neu. Das Ergebnis sieht aus wie eine Ablehnung vor jeglicher Ausgabe, mit dem fallback-Block an erster Stelle. Der abgelehnte Versuch und seine Output-Token erscheinen weiterhin in usage.iterations.



Clientseitiges Fallback mit der SDK-Middleware

Jedes Anthropic SDK enthält eine Refusal-Fallback-Middleware. Du konfigurierst sie einmal auf dem Client mit deiner Liste von Fallback-Modellen. Aufrufe über client.beta.messages wiederholen abgelehnte Anfragen dann automatisch, auf jeder Plattform. Die Middleware sendet außerdem den Beta-Header fallback-credit-2026-07-01 bei jeder Anfrage, die sie verarbeitet, sodass Wiederholungsversuche ohne Einrichtung pro Anfrage neu bepreist werden.



Einrichtung

Übergib die Middleware an den Client-Konstruktor und teile eine BetaFallbackState-Instanz über die Anfragen eines Gesprächs hinweg.

from anthropic import Anthropic, BetaFallbackState, BetaRefusalFallbackMiddleware

# Bei einer Ablehnung wiederholt die Middleware die Anfrage mit dem angegebenen Fallback-Modell und
# sendet automatisch bei jeder verarbeiteten Anfrage den Fallback-Credit-Beta-Header mit.
client = Anthropic(
    middleware=[BetaRefusalFallbackMiddleware([{"model": "claude-opus-4-8"}])],
)

state = BetaFallbackState()  # pins follow-ups to the model that accepted

# Streaming: Bei einer Ablehnung wiederholt die Middleware die Anfrage mit dem Fallback-Modell und
# fügt dessen Events in den offenen Stream ein.
with (
    state,
    client.beta.messages.stream(
        max_tokens=1024,
        model="claude-fable-5",
        messages=[{"role": "user", "content": "Hello, Claude"}],
    ) as stream,
):
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final_message = stream.get_final_message()
print(f"\nserved by: {final_message.model}")

# Non-Streaming: Die Wiederverwendung des State hält die Konversation fixiert.
with state:
    message = client.beta.messages.create(
        max_tokens=1024,
        model="claude-fable-5",
        messages=[{"role": "user", "content": "Hello, Claude"}],
    )
print(f"served by: {message.model}")



Wie sie sich verhält

• Wiederholungsversuche durchlaufen deine Fallback-Liste der Reihe nach. Ein Fallback-Modell, das selbst ablehnt, gibt die Anfrage an den nächsten Eintrag weiter.
• Wenn jedes Modell in der Liste abgelehnt hat, gibt die Middleware die letzte Ablehnung (die Ablehnungsantwort des letzten Modells) zurück, anstatt einen Fehler auszulösen.
• Thinking-Blöcke von Claude Fable 5 werden unverändert durchgereicht: Jeder Wiederholungsversuch sendet deinen ursprünglichen Anfrage-Body erneut, und die einzigen Blöcke, die die Middleware bei späteren Anfragen aus dem Gesprächsverlauf entfernt, sind die fallback-Grenzblöcke, die sie selbst hinzugefügt hat.
• Antworten, die über die Middleware bedient werden, enthalten einen fallback-Content-Block an jeder Modellgrenze, genau wie serverseitige Fallback-Antworten. Die Middleware verwaltet diese Blöcke für dich bei späteren Anfragen.
• Das Modell, das akzeptiert hat, wird in BetaFallbackState aufgezeichnet, sodass Folgeanfragen, die den State teilen, daran gebunden bleiben, anstatt ein Modell erneut zu fragen, das abgelehnt hat.



Ablehnungen in Message Batches

Eine abgelehnte Anfrage in einem Message Batch kommt als result.type: "succeeded" mit stop_reason: "refusal" zurück. Batch-Ergebnisse tragen dasselbe stop_details-Objekt wie synchrone Antworten, du kannst Ablehnungen also entweder über stop_reason oder stop_details.type erkennen. Ein Unterschied: Batch-Ablehnungen erzeugen keine Fallback-Guthaben, daher enthält stop_details bei einem Batch-Ergebnis nie ein fallback_credit_token.

Serverseitiges Fallback ist für Batches nicht verfügbar (eine Batch-Anfrage, die fallbacks enthält, erzeugt ein fehlerhaftes Ergebnis pro Element). Um abgelehnte Batch-Elemente zu wiederholen:

1. Sammle die abgelehnten Elemente aus den Ergebnissen.
2. Entferne die Thinking-Blöcke von Claude Fable 5 aus allen Mehrfach-Turn-Verläufen.
3. Reiche sie auf einem Fallback-Modell als neuen Batch oder als direkte Anfragen erneut ein.



Häufige Fallstricke

• Wiederhole auf einem anderen Modell. Das erneute Senden einer abgelehnten Anfrage an dasselbe Modell führt in der Regel zu einer weiteren Ablehnung. Richte den Wiederholungsversuch auf das Fallback-Modell.
• Budgetiere Wiederholungsversuche pro Anfrage, nicht pro Turn oder pro Session. Ein einzelner Turn kann mehrere Ablehnungen erzeugen, zum Beispiel ein Agent plus seine Sub-Agenten.
• Konfiguriere Fallback auf jedem Anfragepfad. Retry-Handler, Fehlerbehandlungszweige und Hintergrund-Worker brauchen es alle. Ein Handler, der eine Anfrage ohne Fallback erneut ausgibt, verliert den Schutz genau bei den Anfragen, die ihn am wahrscheinlichsten brauchen.
• Gib Sub-Agenten-Aufrufen ihr eigenes Fallback. Der fallbacks-Parameter wird nicht in Modellaufrufe propagiert, die innerhalb der Tool-Ausführung gemacht werden.
• Mache Fallback zu einer Eigenschaft der Anfrage, nicht des Umgebungszustands. Ein geteiltes Flag, ein gecachter Konfigurationswert oder ein globaler Schalter kann aus dem Takt geraten und eine Anfrage stillschweigend ungeschützt lassen. Wenn du nicht bestätigen kannst, dass Fallback aktiv ist, konfiguriere es, anstatt anzunehmen, dass es eingeschaltet ist.
• Instrumentiere Ablehnungen als eigenes Signal. Eine Ablehnung ist ein HTTP 200, Monitoring, das auf Fehlerraten oder 5xx-Antworten aufbaut, sieht sie also nie. Sende ein Event pro Ablehnung und eines pro per Fallback bedienter Antwort (der fallback_message-Eintrag in usage.iterations markiert Letztere) und alarmiere dann bei der Lücke zwischen den beiden Zählungen.
• Verzweige auf stop_reason oder stop_details.type, nicht auf content oder die inneren stop_details-Felder. Das stop_details-Objekt ist bei einer Ablehnung immer vorhanden, aber seine Felder category und explanation können null sein. Prüfe direkt, ob stop_reason gleich "refusal" ist.



Nächste Schritte