Claude 529 overloaded_error — penyebab dan strategi retry yang tepat

529 adalah satu-satunya error Claude yang tidak disebabkan oleh kode Anda: Anthropic sendiri sedang kelebihan beban. Anda tidak dapat memperbaikinya — hanya menanganinya dengan benar. Artinya: lakukan percobaan ulang dengan sabar menggunakan backoff, gunakan model fallback untuk jalur yang sensitif terhadap latensi, dan jangan pernah langsung membuat lonjakan retry yang justru memperparah gangguan.

Error

Respons (HTTP 529)

{
  "type": "error",
  "error": { "type": "overloaded_error",
             "message": "Overloaded" }
}

Ringkasan penyebab dan perbaikan

Penyebab	Perbaikan
Kelebihan beban di sisi penyedia (hari peluncuran, gangguan regional). Berdampak pada semua pelanggan secara bersamaan.	Gunakan backoff dengan jitter; periksa halaman status Anthropic alih-alih menerapkan ulang aplikasi Anda.
Lonjakan beban Anda sendiri bertepatan dengan kapasitas yang sudah berada di bawah tekanan.	Sebarkan pekerjaan batch; penundaan sepuluh menit biasanya cukup untuk mengatasinya.
Tertukar dengan 429: rate limit terlihat serupa di log, tetapi penyebabnya sama sekali berbeda.	429 berarti Anda telah melampaui batas (server sehat); 529 berarti server sedang kelebihan beban (kuota Anda baik-baik saja). Hanya 429 yang memberikan petunjuk Retry-After.
Tidak ada fallback yang ditentukan, sehingga masalah di sisi penyedia diteruskan hingga pengguna akhir.	Tetapkan rantai fallback — dalam keluarga yang sama (Sonnet → Haiku), perilakunya tetap mirip; lintas penyedia (Claude → GPT), Anda juga dapat bertahan dari gangguan total.

Lakukan retry tanpa memperparah gangguan

Perlakukan 529 seperti 429 tanpa Retry-After: gunakan exponential backoff mulai sekitar 2 detik, dengan jitter, batasi pada 30–60 detik, berhenti setelah sekitar lima percobaan, lalu masukkan pekerjaan ke antrean. Jitter adalah bagian yang paling penting: tanpanya, semua klien akan kembali secara bersamaan dan memperpanjang kelebihan beban yang ingin mereka hindari.

Beralih daripada gagal

Untuk jalur yang sensitif terhadap latensi, tentukan rantai fallback. Pada endpoint yang kompatibel dengan OpenAI, Anda hanya perlu mengubah satu string — tanpa SDK kedua dan tanpa akun kedua:

failover.py

PREFERRED = ["claude-sonnet-5", "claude-haiku-4-5", "gpt-5-6-terra"]

def complete(messages):
    last = None
    for model in PREFERRED:
        try:
            return client.chat.completions.create(
                model=model, messages=messages, max_tokens=800)
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            last = e          # überlastet — nächste Stufe versuchen
    raise last

Baru setelah itu periksa kode Anda sendiri

Jika 529 hanya muncul pada satu jenis permintaan sementara panggilan lain pada waktu yang sama berhasil, ini bukan gangguan di seluruh penyedia: periksa apakah jalur tersebut mengirim prompt yang luar biasa besar atau berjalan dalam loop yang rapat. Sebaliknya, jika semua panggilan terdampak secara bersamaan lalu pulih sendiri, penyebabnya adalah kapasitas — pekerjaan tersebut harus ditangani dengan retry dan fallback, bukan refaktor.

Jika Anda melakukan panggilan melalui Kunavo

Kunavo meneruskan Claude melalui lebih dari satu jalur upstream, dan katalog multi-modelnya menjadikan failover lintas penyedia sebagai perubahan nama model pada kunci dan penagihan yang sama — pola di atas tidak memerlukan akun kedua. Error 529 yang tetap sampai kepada Anda tidak pernah ditagihkan. Kapasitas dan harga adalah dua hal yang terpisah; untuk yang kedua, tarif per model tersedia di daftar harga API Claude.

Pertanyaan umum

Apakah 529 adalah kesalahan saya?

Tidak. Ini adalah masalah kapasitas di sisi penyedia. Tanggung jawab Anda hanya memastikan gangguan tidak diperparah (backoff, jitter) dan menyediakan tujuan fallback jika insiden berlangsung lebih lama daripada anggaran latensi Anda.

529 atau 429 — apa perbedaannya?

429 berarti Anda telah melampaui batas, sedangkan server sehat. 529 berarti server itu sendiri sedang kelebihan beban, sementara kuota Anda baik-baik saja. Keduanya dapat dicoba ulang; hanya 429 yang menyertakan petunjuk Retry-After.

Biasanya berapa lama fase 529 berlangsung?

Hal ini tidak dapat diprediksi dan tidak dapat dijamin — karena itu, respons yang tepat adalah backoff yang dibatasi ditambah antrean, bukan waktu tunggu yang ditulis langsung ke dalam kode. Jika jalur Anda memiliki anggaran latensi, gunakan fallback alih-alih menunggu.

Apakah panggilan 529 yang gagal ditagihkan?

Melalui Kunavo, tidak: permintaan yang berakhir dengan error tidak ditagihkan. Dalam kontrak langsung, hal ini bergantung pada aturan penagihan penyedia terkait.

Panduan terkait

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