Ablehnungen und Fallback

Claude Fable 5 enthält Sicherheits-Classifier, die eine Anfrage ablehnen können. Wenn das passiert, erhältst du eine normale Antwort, keinen Fehler, mit stop_reason: "refusal". In der Regel kannst du trotzdem eine Antwort bekommen, indem du dieselbe Anfrage an ein anderes Claude-Modell sendest. Diese Seite zeigt dir, wie du eine Ablehnung erkennst und wie du diesen Retry einrichtest.

Lies diese Seite, wenn du auf Claude Fable 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.

Die vollständige Liste der stop_reason-Werte findest du unter Stop-Reasons und Fallback. Details dazu, wie abgelehnte Anfragen abgerechnet werden und wie du vermeidest, beim Retry doppelt für Prompt-Caching zu bezahlen, findest du unter Fallback-Credit. Der SDK-Helper, der all das kapselt, ist unter SDK-Middleware beschrieben. Ein durchgängiges Beispiel findest du im Fallback- und Billing-Cookbook.

Das einfachste Setup: Gib ein Fallback-Modell in der Anfrage an, und die API übernimmt den Retry.

await client.beta.messages.create({
  model: "claude-fable-5",
  max_tokens: 1024,
  messages,
  betas: ["server-side-fallback-2026-06-01"],
  fallbacks: [{ model: "claude-opus-4-8" }]
});

Die folgenden Abschnitte behandeln, was eine Ablehnungsantwort enthält, wann du serverseitigen oder clientseitigen Fallback verwenden solltest und wie beides 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. Das Feld category benennt den Policy-Bereich, der den Classifier ausgelöst hat. Das Feld explanation ist eine menschenlesbare Beschreibung; der Text ist nicht stabil, also zeige ihn an, statt ihn zu parsen. Beide Felder sind null, wenn die Ablehnung keiner benannten Kategorie zugeordnet werden kann, und null ist ein normaler, dauerhafter Wert und kein Platzhalter. stop_details selbst ist null für jeden anderen Stop-Reason als refusal.

Eine Ablehnung kann vor jeglicher Ausgabe eintreffen oder mitten im Stream nach teilweiser Ausgabe. In beiden Fällen solltest du jede Teilausgabe als unvollständig behandeln und verwerfen.

Einen Fallback-Ansatz wählen

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

Serverseitiger Fallback und die SDK-Middleware wenden Fallback-Credit für dich an, du brauchst diese Seite also nur, wenn du den Retry selbst baust.

Serverseitiger Fallback

Serverseitiger Fallback wiederholt eine abgelehnte Anfrage innerhalb eines einzigen API-Aufrufs. Du gibst bis zu drei Fallback-Modelle an, und wenn Claude Fable 5 ablehnt, führt die API das nächste Modell in der Kette mit derselben Anfrage aus. Du erhältst eine einzige Antwort zurück, die das Modell nennt, das geantwortet hat, sodass dein Nutzer in einem Roundtrip eine Antwort bekommt.

Die Anfrage stellen

Gib die Fallback-Modelle im fallbacks-Parameter an und sende den Beta-Header server-side-fallback-2026-06-01.

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 und thinking nur für diesen Versuch überschreiben.
• Die Anfrage muss als direkte Anfrage an jedes genannte 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.
• Nur eine Ablehnung durch den Sicherheits-Classifier löst den Fallback aus. Ein Ratenlimit, eine Überlastung oder ein Serverfehler beim angeforderten Modell wird unverändert an dich zurückgegeben.

Was die Antwort enthält

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

• Das Top-Level-Feld model gibt das Modell an, das die zurückgegebene Nachricht erzeugt hat, egal ob das das angeforderte Modell oder ein Fallback ist.
• Ein fallback-Content-Block markiert jede Stelle in content, an der die Ausgabe eines Modells in die des nächsten übergeht: {"type": "fallback", "from": {"model": ...}, "to": {"model": ...}}. from.model gibt den Modell-String wieder, den du gesendet hast, wenn der ablehnende Schritt das angeforderte Modell ist. to.model ist immer die aufgelöste ID des Modells, das fortsetzt.

Bei einer Ablehnung vor jeglicher Ausgabe ist der fallback-Block der erste Content-Block:

{
  "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 Array usage.iterations protokolliert jeden Versuch. 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 Schritt und einem fallback_message-Eintrag für den letzten.

Die Konversation fortsetzen

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

Streaming

Bei einer Streaming-Anfrage passiert der Retry auf demselben Stream, und nichts, was du bereits empfangen hast, wird ungültig. Wenn die Ablehnung vor jeglicher Ausgabe passiert, benennt message_start das Fallback-Modell und der fallback-Block ist der erste Content-Block; da message_start wartet, bis der Fallback-Versuch startet, schließt die Zeit bis zum ersten Byte den abgelehnten Versuch ein. Wenn die Ablehnung mitten in der Ausgabe passiert, wird der offene Content-Block geschlossen, der fallback-Block (ein gewöhnliches content_block_start- und content_block_stop-Paar ohne Deltas) markiert die Grenze, und das Fallback-Modell setzt ab der Teilausgabe fort. Nur die text-Blöcke der Teilausgabe werden dem Fallback-Modell als Kontext übergeben; andere Block-Typen bleiben in content. Im Fall mitten in der Ausgabe hat message_start bereits das angeforderte Modell benannt, also lies das bedienende Modell aus dem to.model des fallback-Blocks und aus dem fallback_message-Eintrag in usage.iterations des finalen message_delta.

Bei einer Nicht-Streaming-Anfrage verhält sich eine Ablehnung mitten in der Ausgabe anders: Die Antwort lässt die Teilausgabe 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 zuerst. Der abgelehnte Versuch und seine Output-Token erscheinen trotzdem in usage.iterations.

Clientseitiger Fallback mit der SDK-Middleware

Die TypeScript-, Python-, Go-, Java- und C#-SDKs enthalten eine Refusal-Fallback-Middleware. Du konfigurierst sie einmal auf dem Client mit deiner Liste von Fallback-Modellen. Aufrufe über client.beta.messages wiederholen dann abgelehnte Anfragen automatisch, auf jeder Plattform. Die Middleware sendet außerdem den Beta-Header fallback-credit-2026-06-01 bei jeder Anfrage, die sie verarbeitet, sodass Retries ohne anfrageweise Einrichtung neu bepreist werden.

Einrichtung

Übergib die Middleware an den Client-Konstruktor und teile eine BetaFallbackState-Instanz über die Anfragen einer Konversation hinweg.

Wie sie sich verhält

• Retries durchlaufen deine Fallback-Liste der Reihe nach. Ein Fallback-Modell, das selbst ablehnt, reicht die Anfrage an den nächsten Eintrag weiter.
• Die ursprüngliche Ablehnungsantwort wird nur zurückgegeben, wenn jedes Modell in der Liste abgelehnt hat. Die Middleware wirft dafür keinen Fehler.
• Thinking-Blöcke von Claude Fable 5 werden für dich gehandhabt: Die Middleware entfernt sie aus dem Retry und verwaltet sie in der Konversationshistorie bei späteren Anfragen.
• Antworten, die über die Middleware bedient werden, enthalten an jeder Modellgrenze einen fallback-Content-Block, 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 gepinnt bleiben, statt 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. Das Feld stop_details kann bei Batch-Ergebnissen null sein, also erkenne Ablehnungen, indem du stop_reason direkt prüfst.

Serverseitiger Fallback ist für Batches nicht verfügbar (eine Batch-Anfrage, die fallbacks enthält, erzeugt ein fehlerhaftes Ergebnis pro Item). Um abgelehnte Batch-Items erneut zu versuchen:

1. Sammle die abgelehnten Items aus den Ergebnissen.
2. Entferne die Thinking-Blöcke von Claude Fable 5 aus allen Multi-Turn-Historien.
3. Sende sie auf einem Fallback-Modell als neuen Batch oder als direkte Anfragen erneut.

Häufige Fallstricke

• Wiederhole auf einem anderen Modell. Eine abgelehnte Anfrage erneut an dasselbe Modell zu senden, bringt meist eine weitere Ablehnung. Richte den Retry auf das Fallback-Modell.
• Budgetiere Retries pro Anfrage, nicht pro Turn oder pro Session. Ein einzelner Turn kann mehrere Ablehnungen erzeugen, zum Beispiel ein Agent plus seine Sub-Agents.
• Konfiguriere Fallback auf jedem Anfragepfad. Retry-Handler, Error-Recovery-Zweige und Background-Worker brauchen ihn alle. Ein Handler, der eine Anfrage ohne Fallback erneut absetzt, verliert den Schutz genau bei den Anfragen, die ihn am ehesten brauchen.
• Gib Sub-Agent-Aufrufen ihren eigenen Fallback. Der fallbacks-Parameter propagiert nicht in Modellaufrufe, die innerhalb der Tool-Ausführung gemacht werden.
• Mache Fallback zu einer Eigenschaft der Anfrage, nicht von Umgebungszustand. Ein geteiltes Flag, ein gecachter Config-Wert 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 ihn, statt anzunehmen, dass er an ist.
• Instrumentiere Ablehnungen als eigenes Signal. Eine Ablehnung ist ein HTTP 200, also sieht Monitoring, das auf Fehlerraten oder 5xx-Antworten aufbaut, sie nie. Emittiere ein Event pro Ablehnung und eines pro per Fallback bedienter Antwort (der fallback_message-Eintrag in markiert Letztere), dann alarmiere auf die Lücke zwischen den beiden Zählern.

Nächste Schritte