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. 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 sudah berada di model baru sejak awal.

Anda hanya memerlukan halaman ini ketika Anda membangun percobaan ulang sendiri: 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-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 menolak alih-alih memulai dari awal:



Contoh

Contoh berikut membuat permintaan yang mungkin ditolak dan menukarkan token kredit pada percobaan ulang terhadap Claude Opus 4.8. Ketika sebuah percobaan ulang ditolak, contoh ini menurun melalui tangga penolakan: urutan bentuk percobaan ulang yang semakin sederhana yang dibahas di Ketika percobaan ulang ditolak.

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}
    # Utamakan bentuk continuation kecuali klaimnya 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:
            # Kembali ke body yang tidak diubah, tetap dengan token tersebut
            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
            # 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 berada dalam tahap beta di Claude API, Amazon Bedrock, Claude Platform di AWS, Google Cloud, dan Microsoft Foundry. Penolakan di Message Batches tidak menerbitkan token kredit, dan penukaran hanya berlaku untuk permintaan Messages API langsung: token yang dikirimkan pada permintaan batch diterima tetapi diabaikan.

Model percobaan ulang harus merupakan salah satu target fallback yang diizinkan dari model yang menolak. Target yang diizinkan untuk Claude Fable 5 adalah Claude Opus 4.8 (claude-opus-4-8) dan Claude Opus 5 (claude-opus-5).



Memeriksa bahwa kredit telah diterapkan

Pengembalian dana terlihat di usage pada percobaan ulang. Dibandingkan dengan apa yang akan dilaporkan oleh permintaan yang sama tanpa token, cache_creation_input_tokens lebih rendah, dan cache_read_input_tokens lebih tinggi dengan jumlah yang sama. Pergeseran sebesar nol berarti token dihormati tetapi tidak ada yang perlu dihitung ulang harganya, misalnya karena cache model percobaan ulang sudah hangat.



Ketika percobaan ulang ditolak

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



Referensi

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



Langkah selanjutnya