Error 529 overloaded_error pada API Claude — artinya dan cara mengatasinya

529 adalah satu-satunya error Claude yang tidak disebabkan oleh kode Anda: Anthropic sendiri sedang kelebihan beban. Anda tidak dapat memperbaikinya — tetapi dapat menanganinya dengan baik. Artinya, gunakan retry yang sabar, model cadangan, dan jangan pernah memperburuk insiden dengan percobaan langsung berulang-ulang.

Error

respons (HTTP 529)

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

Ringkasan penyebab dan perbaikan

Penyebab	Perbaikan
Kejenuhan penyedia (hari peluncuran, insiden regional)	Backoff eksponensial dengan jitter. Periksa halaman status penyedia, bukan melakukan deploy ulang.
Lonjakan trafik Anda terjadi saat insiden parsial	Sebarkan pekerjaan batch; menunggu sepuluh menit biasanya sudah cukup untuk menyelesaikannya.
Retry langsung dalam loop	Mencoba lagi saat itu juga akan menggandakan beban dan memperpanjang insiden bagi semua orang, termasuk Anda.

Lakukan retry sebagai pengguna yang bertanggung jawab

Perlakukan 529 seperti 429 tanpa header retry-after: gunakan backoff eksponensial mulai sekitar 2 detik, dengan jitter, batas 30–60 detik, berhenti setelah sekitar 5 percobaan, lalu masukkan pekerjaan ke antrean. Cabang kode yang sama untuk menangani 429 dapat digunakan untuk 529.

retry.py

import time, random
from openai import APIStatusError

def com_retry(fn, tentativas=5):
    for i in range(tentativas):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            espera = min(2 ** i + random.random(), 60)
            time.sleep(espera)
    raise RuntimeError("esgotou as tentativas")

Ganti model, jangan menyerah

Untuk jalur yang sensitif terhadap latensi, tetapkan model cadangan: dalam keluarga yang sama (Sonnet → Haiku), perilakunya tetap mirip; antarpenyedia (Claude → GPT), Anda dapat bertahan melewati seluruh insiden. Pada endpoint yang kompatibel dengan OpenAI, ini cukup dilakukan dengan mengganti satu string.

failover.py

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

def completar(mensagens):
    ultimo = None
    for modelo in PREFERIDOS:
        try:
            return client.chat.completions.create(
                model=modelo, messages=mensagens, max_tokens=800)
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            ultimo = e          # saturado — tenta o próximo
    raise ultimo

Jangan samakan 529 dengan 429 atau 402

429 berarti Anda melewati batas Anda (server baik-baik saja). 529 berarti server sedang kelebihan beban (kuota Anda baik-baik saja). 402 berarti saldo tidak mencukupi. Ketiganya tampak mirip di log tetapi memiliki perbaikan yang sepenuhnya berbeda: hanya 429 dan 529 yang perlu diulang.

Jika Anda melakukan panggilan melalui Kunavo

Di Kunavo, katalog multimodel yang sama tersedia di balik satu kunci dan satu saldo, sehingga failover antarpenyedia dalam contoh di atas cukup dilakukan dengan mengganti nama model — tidak memerlukan akun kedua atau pendaftaran kedua. Permintaan yang gagal tidak ditagihkan. Kapasitas dan harga adalah dua pertanyaan terpisah; untuk pertanyaan kedua, tarif per token tersedia di panduan harga API Claude kami.

Pertanyaan umum

Apakah error 529 adalah kesalahan saya?

Tidak. Ini adalah masalah kapasitas di sisi penyedia. Tanggung jawab Anda hanya tidak memperburuk masalah (gunakan backoff dengan jitter) dan memiliki tujuan migrasi jika insiden berlangsung lebih lama daripada anggaran latensi Anda.

Apa perbedaan antara 529 dan 429?

429 berarti Anda melampaui batas; 529 berarti server sedang kelebihan beban. Keduanya dapat diulang, tetapi biasanya hanya 429 yang disertai petunjuk retry-after.

Apakah saya akan dikenai biaya untuk permintaan yang menghasilkan 529?

Seharusnya tidak — permintaan tersebut tidak menghasilkan token. Di Kunavo, permintaan yang gagal tidak dipotong dari saldo.

Panduan terkait

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