Penolakan dan fallback

Claude Fable 5 menyertakan "safety classifiers" (pengklasifikasi keamanan) yang dapat menolak sebuah permintaan. Ketika itu terjadi, Anda menerima respons normal, bukan error, dengan stop_reason: "refusal". Anda biasanya masih bisa mendapatkan jawaban dengan mengirim permintaan yang sama ke model Claude lain. Halaman ini menunjukkan cara mengenali penolakan dan cara menyiapkan percobaan ulang tersebut.

Baca halaman ini ketika Anda membangun dengan Claude Fable 5 dan ingin permintaan yang ditolak diteruskan ke model lain secara otomatis. Halaman ini juga berlaku ketika Anda baru saja melihat "refusal" dalam respons dan ingin tahu apa yang harus dilakukan selanjutnya.

Halaman terkait:

• Stop reasons dan fallback: daftar lengkap nilai stop_reason.
• Fallback credit: bagaimana permintaan yang ditolak ditagih, dan cara menghindari membayar dua kali untuk caching prompt pada percobaan ulang.
• SDK middleware: helper SDK yang membungkus semua ini.
• Cookbook fallback dan penagihan: contoh lengkap dari awal hingga akhir.

Pengaturan paling sederhana: sebutkan model fallback pada permintaan, dan API akan menangani percobaan ulangnya.

client = Anthropic()

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-06-01"],
)

Bagian-bagian di bawah ini membahas apa yang terkandung dalam respons penolakan, kapan menggunakan fallback sisi server atau sisi klien, dan bagaimana masing-masing ditagih.



Seperti apa bentuk penolakan

Penolakan adalah respons HTTP 200 yang berhasil dengan 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
  }
}

Objek stop_details menjelaskan penolakan tersebut:

• category: menyebutkan area kebijakan yang memicu classifier.
• explanation: deskripsi yang dapat dibaca manusia. Teksnya tidak stabil, jadi tampilkan saja daripada mem-parse-nya.
• Kedua field bernilai null ketika penolakan tidak dipetakan ke kategori bernama. Nilai null tersebut adalah nilai normal dan permanen, bukan placeholder.
• stop_details itu sendiri bernilai null untuk setiap stop reason selain refusal.

Penolakan dapat tiba sebelum output apa pun, atau di tengah stream setelah output parsial. Dalam kedua kasus, perlakukan output parsial apa pun sebagai tidak lengkap dan buang.



Memilih pendekatan fallback

Ada tiga cara untuk mencoba ulang permintaan yang ditolak pada model lain. Pilihan yang tepat bergantung pada di mana Anda menjalankannya dan seberapa banyak kontrol yang Anda butuhkan.

Fallback sisi server dan SDK middleware menerapkan fallback credit untuk Anda. Anda hanya memerlukan halaman Fallback credit ketika Anda membangun percobaan ulang sendiri.



Fallback sisi server

Fallback sisi server mencoba ulang permintaan yang ditolak di dalam satu panggilan API. Anda menyebutkan hingga tiga model fallback, dan ketika Claude Fable 5 menolak, API menjalankan model berikutnya dalam rantai pada permintaan yang sama. Anda mendapatkan kembali satu respons yang menyebutkan model yang menjawab, sehingga pengguna Anda mendapatkan jawaban dalam satu round trip.



Membuat permintaan

Sebutkan model fallback dalam parameter fallbacks dan kirim header beta server-side-fallback-2026-06-01.

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-06-01"],
)

# Entri fallback_message di usage.iterations berarti model fallback dijalankan;
# padukan dengan stop_reason untuk memastikan fallback yang memberikan respons.
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,
        }
    )
)

Beberapa aturan berlaku untuk daftar fallbacks:

• Entri dicoba secara berurutan. Setiap entri harus berbeda dari entri lainnya dan dari model yang diminta.
• Setiap entri harus merupakan salah satu target yang diizinkan untuk model yang diminta. Dengan header beta diatur, daftar tersebut dipublikasikan sebagai allowed_fallback_models pada entri model di Models API.
• Setiap entri menyebutkan model dan dapat meng-override max_tokens dan thinking hanya untuk percobaan tersebut.
• Permintaan harus valid sebagai permintaan langsung ke setiap model yang disebutkan. Jika model fallback tidak mendukung fitur yang digunakan permintaan, API menolak permintaan tersebut di awal.
• Hanya penolakan safety classifier yang memicu fallback. Batas laju, overload, atau error server pada model yang diminta dikembalikan kepada Anda apa adanya.



Apa yang terkandung dalam respons

Respons terlihat seperti pesan lainnya, dengan dua tambahan:

• Field model tingkat atas melaporkan model yang menghasilkan pesan yang dikembalikan, baik itu model yang diminta atau fallback.
• Blok konten fallback menandai setiap titik dalam content di mana output satu model beralih ke model berikutnya: {"type": "fallback", "from": {"model": ...}, "to": {"model": ...}}.
  • from.model menggemakan string model yang Anda kirim ketika hop yang menolak adalah model yang diminta.
  • to.model selalu merupakan ID yang di-resolve dari model yang melanjutkan.

Pada penolakan sebelum output apa pun, blok fallback adalah blok konten pertama:

{
  "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
      }
    ]
  }
}

Array usage.iterations mencatat setiap percobaan. Model yang menolak muncul sebagai entri message biasa, dan model yang melayani giliran muncul sebagai entri fallback_message. Jika setiap model dalam rantai menolak, respons adalah penolakan dari model terakhir, dengan entri message untuk setiap hop sebelumnya dan entri fallback_message untuk yang terakhir.



Melanjutkan percakapan

Pada giliran berikutnya, kirim kembali konten asisten seperti yang Anda terima. Setelah fallback di tengah output, content dapat menyertakan tipe blok yang dihasilkan model yang menolak sebelum handoff; tabel di bawah ini mencakup mana yang harus dipertahankan dan mana yang harus dibuang ketika Anda menggemakan giliran tersebut.



Streaming

Pada permintaan streaming, percobaan ulang terjadi pada stream yang sama, dan tidak ada yang sudah Anda terima yang dibatalkan. Apa yang Anda lihat bergantung pada kapan penolakan terjadi.

Ketika penolakan terjadi sebelum output apa pun:

• message_start menyebutkan model fallback, dan blok fallback adalah blok konten pertama.
• Karena message_start menunggu percobaan fallback dimulai, waktu ke byte pertama mencakup percobaan yang ditolak.

Ketika penolakan terjadi di tengah output:

• Blok konten yang terbuka ditutup, dan blok fallback (pasangan content_block_start dan content_block_stop biasa tanpa delta) menandai batasnya.
• Model fallback melanjutkan dari output parsial. Hanya blok text dari output parsial yang diteruskan ke model fallback sebagai konteks; tipe blok lainnya tetap berada di content.
• message_start sudah menyebutkan model yang diminta, jadi baca model yang melayani dari to.model pada blok fallback dan dari entri fallback_message di usage.iterations pada message_delta terakhir.



Respons non-streaming

Pada permintaan non-streaming, penolakan di tengah output berperilaku berbeda: respons menghilangkan output parsial dari model yang ditolak, dan model fallback menjawab dari awal. Hasilnya terlihat seperti penolakan sebelum output apa pun, dengan blok fallback di awal. Percobaan yang ditolak dan token outputnya tetap muncul di usage.iterations.



Fallback sisi klien dengan SDK middleware

SDK TypeScript, Python, Go, Java, dan C# menyertakan middleware refusal-fallback. Anda mengonfigurasinya sekali pada klien dengan daftar model fallback Anda. Panggilan melalui client.beta.messages kemudian mencoba ulang permintaan yang ditolak secara otomatis, pada platform apa pun. Middleware juga mengirim header beta fallback-credit-2026-06-01 pada setiap permintaan yang ditanganinya, sehingga percobaan ulang dihargai ulang tanpa pengaturan per-permintaan.



Menyiapkannya

Teruskan middleware ke konstruktor klien, dan bagikan satu instance BetaFallbackState di seluruh permintaan dalam sebuah percakapan.

# Saat terjadi penolakan, middleware mencoba ulang pada model fallback yang terdaftar dan
# secara otomatis mengirim header beta fallback-credit pada setiap permintaan yang ditanganinya.
client = Anthropic(
    middleware=[BetaRefusalFallbackMiddleware([{"model": "claude-opus-4-8"}])],
)

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

# Streaming: saat terjadi penolakan, middleware mencoba ulang pada model fallback dan
# menyambungkan event-nya ke stream yang sedang terbuka.
with (
    state,
    client.beta.messages.stream(
        max_tokens=1024,
        model="claude-fable-5",
        messages=[{"role": "user", "content": "Hello, Claude"}],
    ) as stream,
):
    for event in stream:
        if event.type == "text":
            print(event.text, end="", flush=True)
    final_message = stream.get_final_message()
print(f"\nserved by: {final_message.model}")

# Non-streaming: menggunakan kembali state membuat percakapan tetap terikat.
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}")



Bagaimana perilakunya

• Percobaan ulang menelusuri daftar fallback Anda secara berurutan. Model fallback yang juga menolak meneruskan permintaan ke entri berikutnya.
• Respons penolakan asli dikembalikan hanya ketika setiap model dalam daftar telah menolak. Middleware tidak memunculkan error untuk itu.
• Blok thinking dari Claude Fable 5 ditangani untuk Anda: middleware menghapusnya dari percobaan ulang dan mengelolanya dalam riwayat percakapan pada permintaan selanjutnya.
• Respons yang dilayani melalui middleware menyertakan blok konten fallback di setiap batas model, sama seperti respons fallback sisi server. Middleware mengelola blok tersebut untuk Anda pada permintaan selanjutnya.
• Model yang menerima dicatat dalam BetaFallbackState, sehingga permintaan lanjutan yang berbagi state tersebut tetap dipatok padanya daripada bertanya ulang ke model yang menolak.



Penolakan dalam Message Batches

Permintaan yang ditolak dalam Message Batch kembali sebagai result.type: "succeeded" dengan stop_reason: "refusal". Field stop_details mungkin bernilai null pada hasil batch, jadi deteksi penolakan dengan memeriksa stop_reason secara langsung.

Fallback sisi server tidak tersedia untuk batch (permintaan batch yang menyertakan fallbacks menghasilkan hasil error per-item). Untuk mencoba ulang item batch yang ditolak:

1. Kumpulkan item yang ditolak dari hasil.
2. Hapus blok thinking Claude Fable 5 dari riwayat multi-giliran mana pun.
3. Kirim ulang pada model fallback sebagai batch baru atau sebagai permintaan langsung.



Kesalahan umum

• Coba ulang pada model yang berbeda. Mengirim ulang permintaan yang ditolak ke model yang sama biasanya menghasilkan penolakan lagi. Arahkan percobaan ulang ke model fallback.
• Anggarkan percobaan ulang per permintaan, bukan per giliran atau per sesi. Satu giliran dapat menghasilkan beberapa penolakan, misalnya agen ditambah sub-agennya.
• Konfigurasikan fallback pada setiap jalur permintaan. Handler percobaan ulang, cabang pemulihan error, dan background worker semuanya membutuhkannya. Handler yang mengirim ulang permintaan tanpa fallback kehilangan perlindungan tepat pada permintaan yang paling mungkin membutuhkannya.
• Berikan panggilan sub-agen fallback-nya sendiri. Parameter fallbacks tidak menyebar ke panggilan model yang dibuat dari dalam eksekusi alat.
• Jadikan fallback sebagai properti permintaan, bukan state ambien. Flag bersama, nilai konfigurasi yang di-cache, atau toggle global dapat menjadi tidak sinkron dan diam-diam membiarkan permintaan tidak terlindungi. Ketika Anda tidak dapat memastikan fallback aktif, konfigurasikan daripada mengasumsikan sudah aktif.
• Instrumentasikan penolakan sebagai sinyal tersendiri. Penolakan adalah HTTP 200, jadi pemantauan yang dibangun berdasarkan tingkat error atau respons 5xx tidak pernah melihatnya. Emit satu event per penolakan dan satu per respons yang dilayani fallback (entri fallback_message di usage.iterations menandai yang terakhir), lalu buat alert pada selisih antara kedua hitungan tersebut.
• Bercabang berdasarkan stop_reason, bukan stop_details atau content. stop_details bersifat informasional dan dapat bernilai null pada penolakan. Periksa stop_reason sama dengan "refusal" secara langsung.



Langkah selanjutnya