Batas waktu permintaan Claude API dan “streaming sangat disarankan”

Biasanya ada tiga batas waktu antara Anda dan model — milik SDK Anda, milik perantara, dan aturan penyedia untuk panggilan panjang tanpa streaming — dan yang terpendeklah yang berlaku. Hanya menaikkan batas waktu SDK adalah alasan masalah ini terus terjadi setelah Anda mengira telah memperbaikinya.

Error

dua bentuk

# Rejected before generating, for a long non-streaming request:
{"type":"error","error":{"type":"invalid_request_error",
 "message":"Streaming is strongly recommended for operations that may take
 longer than 10 minutes."}}

# Or the client-side companion, with no response at all:
APITimeoutError: Request timed out.

Ringkasan penyebab dan perbaikan

Penyebab	Perbaikan
Generasi panjang tanpa streaming	Gunakan streaming. Penyelesaian panjang diharapkan dialirkan, bukan ditunggu.
Batas waktu klien SDK lebih pendek daripada waktu generasi	Naikkan batasnya — tetapi naikkan juga batas perantara, atau tidak ada yang berubah.
Proxy, load balancer, atau fungsi serverless yang membatasi permintaan	Temukan batas terpendek dalam rantai; itulah batas yang sedang Anda temui.
Koneksi diterima, lalu tidak pernah dijawab	Ini adalah hang, bukan jawaban yang lambat. Batasi waktu hingga byte pertama secara terpisah.

Stream apa pun yang mungkin berlangsung lebih dari beberapa menit

Selain menghindari batas, streaming memberi sinyal kelangsungan: token yang terus tiba berarti model sedang bekerja, sehingga hang dapat dibedakan dari kemajuan yang lambat. Dalam satu panggilan pemblokiran, keduanya tampak identik sampai batas waktu habis.

Naikkan setiap batas waktu dalam rantai, bukan hanya milik SDK

Orang hampir selalu mengubah klien lalu berhenti. Jika reverse proxy atau platform serverless membatasi permintaan di bawah batas waktu klien baru Anda, batas tersebut tetap menang dan gejalanya tidak berubah.

client.py

from anthropic import Anthropic

# Client timeout is only one of the limits in play.
client = Anthropic(api_key=KEY, timeout=600.0)

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=8192,
    messages=[{"role": "user", "content": prompt}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Batasi waktu hingga byte pertama secara terpisah dari durasi total

Ini adalah dua kegagalan berbeda yang memerlukan dua solusi berbeda. Batas waktu byte pertama yang singkat segera mendeteksi koneksi mati; batas waktu total yang longgar memungkinkan generasi yang benar-benar panjang selesai. Satu batas waktu gabungan tidak dapat melakukan keduanya.

Pastikan retry aman sebelum menambahkannya

Permintaan yang mengalami timeout di sisi Anda mungkin sudah selesai di sisi upstream. Jika pekerjaan memiliki efek samping atau Anda ditagih per panggilan, tambahkan idempotensi pada lapisan Anda sebelum menambahkan loop retry.

Jika Anda melakukan panggilan melalui Kunavo

Kunavo menerbitkan angkanya sendiri, jadi Anda tidak perlu menemukannya: Kunavo menunggu paling lama 240 detik untuk header respons upstream, dan jawaban tanpa streaming biasanya hanya mengirim header setelah selesai, sehingga panggilan tanpa streaming yang memerlukan waktu lebih lama tidak akan selesai melalui gateway — gunakan streaming. Batas 240 detik hanya berlaku hingga header diterima dan dilepas segera setelah header tiba, sehingga tidak pernah memotong stream panjang; tidak ada batas lain di gateway yang membatasi panjang stream. Hal yang dapat mengakhirinya adalah keheningan: 300 detik tanpa satu byte pun dari upstream, atau 600 detik tanpa satu byte pun pada koneksi ke Anda. Rute gambar, video, dan musik sinkron menahan koneksi hingga 540 detik saat render selesai, masih dalam jendela 600 detik, karena proses render memang dapat memerlukan beberapa menit. Permintaan yang mengalami timeout sebelum header dihitung sebagai kegagalan kanal, dicoba ulang pada kanal model berikutnya jika dikonfigurasi, dan dicatat dengan biaya nol.

Pertanyaan umum

Apakah permintaan yang mengalami timeout tetap ditagih?

Di Kunavo, tidak — permintaan yang gagal dicatat dengan biaya nol. Penagihan langsung oleh penyedia bergantung pada apakah generasi benar-benar terjadi.

Mengapa streaming menghindari batas tersebut?

Respons dimulai dalam hitungan detik dan koneksi tetap aktif, sehingga tidak ada periode keheningan yang cukup panjang untuk memicu timeout.

Berapa batas waktu klien yang harus saya gunakan?

Lebih lama daripada generasi realistis terburuk Anda, dipasangkan dengan batas waktu byte pertama terpisah yang singkat. Satu batas waktu gabungan yang panjang mengubah setiap hang menjadi penundaan selama beberapa menit.

Panduan terkait

Detail semantik error lainnya tersedia di referensi error; mendapatkan kunci hanya perlu satu menit melalui pendaftaran dan panduan autentikasi.