Kredit fallback
Hindari membayar biaya prompt-cache dua kali saat Anda mencoba ulang permintaan yang ditolak pada model lain.
Prompt cache bersifat per-model. Ketika sebuah model menolak permintaan dan Anda mencoba ulang pada model lain, prefiks percakapan yang sudah di-cache untuk model pertama harus ditulis ke dalam cache model baru dari awal. Penulisan cache (cache write) lebih mahal daripada pembacaan cache (cache read). "Fallback credit" (kredit fallback) menghilangkan biaya tambahan tersebut. Penolakan membawa token kredit, Anda mengirimkan kembali token tersebut pada percobaan ulang, dan percobaan ulang ditagih seolah-olah percakapan telah berada pada model baru sejak awal.
Anda memerlukan halaman ini hanya jika 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 baru bagi Anda.
Alur dasar
Ikut serta dengan header beta
Kirim permintaan yang mungkin ditolak dengan header
anthropic-beta: fallback-credit-2026-07-01. Headerserver-side-fallback-2026-07-01juga memberikan field yang sama, dan header sebelumnyafallback-credit-2026-06-01tetap diterima dan memberikan field yang sama.Baca dua field dari penolakan
Pada penolakan,
stop_detailsmenyertakan dua field:fallback_credit_token: string opaque yang merepresentasikan kredit.fallback_has_prefill_claim: Boolean yang memberi tahu Anda bentuk body percobaan ulang mana yang harus digunakan.
Keduanya bernilai
nullketika tidak ada kredit yang tersedia untuk penolakan tersebut.Bangun percobaan ulang
Mulai dari body permintaan yang ditolak. Atur
modelke model fallback dan tambahkan token sebagai parameter tingkat atasfallback_credit_token. Pilih bentuk body dari tabel berikut.Kirim percobaan ulang dengan header yang sama
Kirim percobaan ulang dengan header beta
fallback-credit-2026-07-01yang sama. Percobaan ulang memerlukan header tersebut untuk menukarkan token.
Field fallback_has_prefill_claim memberi tahu Anda apakah percobaan ulang dapat melanjutkan output parsial dari model yang menolak alih-alih memulai dari awal:
fallback_has_prefill_claim | Body percobaan ulang |
|---|---|
true | Body permintaan yang ditolak, tanpa perubahan, ditambah satu pesan asisten yang ditambahkan di akhir yang content-nya menyalin content dari respons yang ditolak. Model percobaan ulang melanjutkan respons dari titik di mana model yang menolak berhenti, dan panggilan alat server yang telah selesai tidak dieksekusi ulang. |
false | Body permintaan yang ditolak, tanpa perubahan. |
Contoh
Contoh berikut membuat permintaan yang mungkin ditolak dan menukarkan token kredit pada percobaan ulang terhadap Claude Opus 4.8. Ketika upaya 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 claim bernilai 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
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 fitur ini berfungsi
Kredit fallback berada dalam tahap beta di Claude API, Amazon Bedrock, Claude Platform on 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 diteruskan pada permintaan batch diterima tetapi diabaikan.
Model percobaan ulang harus merupakan salah satu target fallback yang diizinkan untuk model yang menolak. Untuk Claude Fable 5.1 dan Claude Fable 5, target tersebut adalah Claude Opus 4.8 (claude-opus-4-8) dan Claude Opus 5 (claude-opus-5).
Di Claude API dan Claude Platform on AWS, daftar target dipublikasikan sebagai allowed_fallback_models pada entri setiap model di Models API ketika header beta server-side-fallback-2026-07-01 diatur. Daftar ini belum terlihat hanya dengan header fallback-credit-* saja. Daftar ini tidak diekspos di Amazon Bedrock, Google Cloud, atau Microsoft Foundry.
Memeriksa bahwa kredit telah diterapkan
Pengembalian biaya terlihat di usage 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 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 tidak berhasil, API mengembalikan error 400 yang memberi tahu Anda apa yang harus dicoba selanjutnya.
Kelanjutan ditolak: kirim ulang body tanpa perubahan
Jika percobaan ulang yang menambahkan pesan asisten ditolak dengan error 400, kirim ulang body permintaan yang ditolak tanpa perubahan, tetap dengan token.
Token ditolak: hapus token
Jika body tanpa perubahan juga ditolak dengan error 400 yang pesannya menyebut
fallback_credit_token, coba ulang tanpa token. Kredit hangus, tetapi percobaan ulang itu sendiri berhasil.
Penolakan ini bersifat sementara, bukan keputusan atas bentuk percobaan ulang Anda. Coba ulang permintaan yang sama, dengan token yang sama, dalam jendela lima menit token tersebut. Jangan berpindah ke langkah berikutnya dalam tangga.
Referensi
Bagian-bagian berikut membahas kasus tepi dan aturan penukaran lengkap. Sebagian besar integrasi tidak memerlukannya.
Penukaran membandingkan percobaan ulang dengan permintaan yang ditolak. Setiap field yang membentuk prompt harus cocok persis. Field yang tidak membentuk prompt boleh berubah pada percobaan ulang.
| Aturan | Field |
|---|---|
| Harus cocok persis | system, messages, tools, tool_choice, thinking, dan cache_control, ditambah output_config, mcp_servers, context_management, dan container ketika Anda menggunakannya |
| Boleh berubah pada percobaan ulang | model, max_tokens, stop_sequences, temperature, top_p, top_k, stream, metadata, dan service_tier |
Bentuk kelanjutan (fallback_has_prefill_claim: true) adalah satu-satunya pengecualian terhadap kecocokan messages: bentuk ini menambahkan tepat satu pesan asisten di akhir messages.
Jangan menghapus blok thinking atau redacted_thinking dari giliran sebelumnya pada percobaan ulang, meskipun percobaan ulang biasa tanpa token umumnya menghapusnya. Body harus cocok dengan permintaan yang ditolak, dan server menangani blok-blok tersebut sendiri.
Kirim header anthropic-beta yang sama pada percobaan ulang seperti pada permintaan yang ditolak. Header beta yang ada pada salah satu dari dua permintaan tetapi tidak pada yang lain dapat menggagalkan kecocokan bahkan ketika body-nya identik. Error 400 yang dihasilkan membawa pesan request body ... does not match yang sama seperti perbedaan body, sehingga perbedaan header mudah disalahartikan sebagai masalah body. Secara khusus, jangan menambah atau menghapus header beta berdasarkan model mana yang ditargetkan permintaan.
Dua keluarga header dikecualikan dari kecocokan, demi kepentingan percobaan ulang:
server-side-fallback-*: percobaan ulang harus menghapus parameterfallbacks, dan menghapus header ini bersamanya tidak menyebabkan ketidakcocokan.fallback-credit-*: pertahankan header ini pada kedua permintaan. Percobaan ulang memerlukannya untuk menukarkan token.
Field ini bernilai null hanya ketika token juga null, sehingga nilai yang Anda amati saat memegang token tidak pernah null. Field ini masih bisa tidak ada (None di SDK bertipe) di Amazon Bedrock, Google Cloud, dan Microsoft Foundry selama dukungan mereka untuk field ini diluncurkan. Dalam kasus itu, perlakukan bentuk percobaan ulang sebagai tidak diketahui, bukan sebagai false. Coba bentuk pesan-asisten-yang-ditambahkan terlebih dahulu, dan andalkan penanganan penolakan di Ketika percobaan ulang ditolak, yang kembali ke body tanpa perubahan.
Ketika token penolakan mendukung bentuk kelanjutan, content respons hanya membawa output model itu sendiri, dan penjelasan penolakan disampaikan di stop_details.explanation. Oleh karena itu, Anda dapat menyalin content ke dalam pesan asisten yang ditambahkan apa adanya.
Dua penyesuaian mungkin masih diperlukan sebelum mengirim:
- Jika blok terakhir yang Anda kirim adalah blok
text, hapus whitespace di akhirnya. - Hilangkan blok
tool_usesisi klien apa pun yang tidak memilikitool_resultyang cocok.
Jika content yang disalin menyertakan blok fallback dari fallback sisi server sebelumnya, pertahankan blok tersebut tepat di tempat ia muncul. Blok ini diterima pada permintaan apa pun tanpa header beta. API menggunakan posisinya untuk memvalidasi blok thinking di sekitarnya, sehingga permintaan yang menyalin blok thinking dari kedua sisi batas tersebut akan ditolak jika blok itu dihilangkan atau dipindahkan.
Token hanya dapat ditukarkan dari organisasi dan workspace yang menerima penolakan, termasuk di Microsoft Foundry. Di Amazon Bedrock dan Google Cloud, yang tidak memiliki workspace, token terikat pada identitas pemanggil platform sebagai gantinya.
Token kedaluwarsa lima menit setelah penolakan. Setelah itu, kirim percobaan ulang tanpanya. Token juga bersifat stateless: server tidak menyimpan apa pun tentangnya, dan tidak ada endpoint untuk memeriksa atau mencabutnya.
Ketika penolakan tiba setelah alat server sudah dieksekusi dalam permintaan, token hanya dapat ditukarkan dengan melanjutkan respons parsial. Pembatasan itulah yang mencegah panggilan alat yang telah selesai berjalan, dan ditagih, lagi.
Oleh karena itu, satu kombinasi dapat membuat token tidak dapat ditukarkan dengan bentuk mana pun, ketika kedua hal berikut benar:
- Permintaan menggunakan
output_config.formatatautool_choiceyang memaksa penggunaan alat. Salah satunya mengesampingkan bentuk pesan-asisten-yang-ditambahkan. - Penolakan tiba setelah alat server dieksekusi. Itu mengesampingkan body tanpa perubahan.
Jika percobaan ulang body-tanpa-perubahan ditolak dengan error 400 yang menyatakan token harus ditukarkan dengan melanjutkan respons parsial, buang token tersebut. Percobaan ulang tanpanya berhasil, tetapi akan menjalankan ulang dan menagih ulang alat server yang telah selesai. Tampilkan biaya atau error tersebut kepada pemanggil Anda daripada mencoba ulang secara diam-diam.
Langkah selanjutnya
Deteksi penolakan dan pilih antara fallback sisi server, middleware SDK, dan percobaan ulang manual.
Bagaimana pembacaan cache dan penulisan cache ditagih.
Setiap nilai stop_reason dan cara menanganinya.
Helper SDK yang menerapkan kredit fallback secara otomatis.
Was this page helpful?