Kredit fallback

Cache prompt bersifat per-model. Ketika Claude Fable 5 menolak sebuah permintaan dan Anda mencoba ulang pada model lain, prefiks percakapan yang sudah di-cache untuk Claude Fable 5 harus ditulis ke dalam cache model baru dari awal, dan penulisan cache lebih mahal daripada pembacaan cache. Kredit fallback menghilangkan biaya tambahan tersebut: penolakan membawa token kredit, Anda menyertakan kembali token tersebut pada percobaan ulang, dan percobaan ulang ditagih seolah-olah percakapan telah berada di model baru sejak awal.

Anda memerlukan halaman ini hanya ketika Anda membangun percobaan ulang sendiri: pada SDK Ruby atau PHP, melalui HTTP mentah, atau dengan logika percobaan ulang kustom. Fallback sisi server dan middleware SDK menerapkan kredit fallback secara otomatis. Jika Anda menggunakan salah satunya, lewati halaman ini.

Penolakan dan fallback membahas cara mendeteksi penolakan dan memilih pendekatan fallback. Caching prompt menjelaskan pembacaan cache dan penulisan cache jika istilah tersebut masih baru bagi Anda.

Alur dasar

Field fallback_has_prefill_claim memberi tahu Anda apakah percobaan ulang dapat melanjutkan output parsial dari model yang ditolak alih-alih memulai dari awal:

Contoh

Contoh di bawah ini membuat permintaan yang mungkin ditolak, menukarkan token kredit pada percobaan ulang terhadap Claude Opus 4.8, dan menurunkan tingkatannya melalui tangga penolakan yang dibahas dalam Ketika percobaan ulang ditolak.

client = Anthropic()

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


def send(model, body):
    return client.beta.messages.create(
        model=model, betas=["fallback-credit-2026-06-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}
    # Utamakan bentuk kelanjutan kecuali klaimnya False
    if details.fallback_has_prefill_claim is not False:
        # Gemakan konten penolakan, hapus spasi kosong di akhir dari
        # blok teks terakhir (validator prefill menolaknya; pencocokan sisi server
        # menoleransi editan ini). Permintaan yang memakai alat juga menghilangkan
        # blok tool_use tak berpasangan, lalu hapus lagi spasi kosong setelah penghilangan.
        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 str(error):
            raise  # Transient: retry with the token within its five-minute window
        try:
            # Kembali ke isi yang tidak diubah, tetap dengan token tersebut
            response = send("claude-opus-4-8", exact_body)
        except BadRequestError as error:
            if "redemption temporarily unavailable" in str(error):
                raise  # Transient: retry with the token within its five-minute window
            # Token itu sendiri ditolak: lepaskan dan coba lagi tanpanya.
            response = send("claude-opus-4-8", request)

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

Di mana ini berfungsi

Kredit fallback tersedia dalam versi beta pada Claude API, Claude Platform di AWS, Amazon Bedrock, Vertex AI, dan Microsoft Foundry. Token kredit yang dikembalikan dalam hasil Message Batches tidak dapat ditukarkan; penukaran hanya berlaku untuk permintaan Messages API langsung.

Model percobaan ulang harus merupakan salah satu target fallback yang diizinkan dari model yang ditolak. Pada saat peluncuran, target yang diizinkan untuk Claude Fable 5 adalah Claude Opus 4.8 (claude-opus-4-8).

Memeriksa bahwa kredit telah diterapkan

Pengembalian dana terlihat dalam usage percobaan ulang: cache_creation_input_tokens lebih rendah, dan cache_read_input_tokens lebih tinggi dengan jumlah yang sama, dibandingkan dengan yang akan dilaporkan oleh permintaan yang sama tanpa token. Pergeseran sebesar nol berarti token dihormati tetapi tidak ada yang perlu dihargai ulang, misalnya karena cache model percobaan ulang sudah hangat.

Ketika percobaan ulang ditolak

Sebagian besar percobaan ulang berhasil ditukarkan pada upaya pertama. Ketika tidak berhasil, API mengembalikan error 400 yang memberi tahu Anda apa yang harus dicoba selanjutnya.

Referensi

Bagian-bagian di bawah ini membahas kasus-kasus khusus dan aturan penukaran lengkap. Sebagian besar integrasi tidak memerlukannya.

Langkah selanjutnya