Claude API 429 rate_limit_error — penyebab dan perbaikan yang efektif

429 dari Claude API berarti Anda melewati salah satu batas per menit Anthropic — permintaan, token input, atau token output. Solusinya jarang hanya "menunggu lebih lama": patuhi retry-after, tambahkan backoff dengan jitter, dan ratakan lonjakan. Berikut panduan lengkapnya.

Error

respons (HTTP 429)

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Number of request tokens has exceeded your per-minute rate limit"
  }
}

Ringkasan penyebab dan perbaikan

Penyebab	Perbaikan
Batas requests-per-minute (RPM) tercapai	Antrekan permintaan di sisi klien; patuhi header retry-after sebelum melakukan retry.
Batas input-tokens-per-minute (ITPM) tercapai — prompt besar, sedikit permintaan	Ringkas konteks yang diambil, dan aktifkan prompt caching agar token yang di-cache tidak lagi dihitung terhadap batas pada paket yang mendukungnya.
Batas output-tokens-per-minute (OTPM) tercapai	Tetapkan max_tokens secara realistis — OTPM sering menjadi batas pertama untuk generasi panjang.
Trafik melonjak (cron menjalankan semuanya pada :00)	Tambahkan jitter pada jadwal; sebarkan pekerjaan batch sepanjang satu menit.

Baca respons sebelum melakukan retry

Anthropic mengembalikan header retry-after yang berisi jumlah detik untuk menunggu, dan pesan error menyebutkan batas yang Anda lewati. Melakukan retry langsung tanpa membacanya adalah cara satu 429 berubah menjadi badai 429.

Tambahkan backoff eksponensial dengan jitter

Lakukan retry hanya untuk status yang dapat diulang (429, 500, 529), jangan pernah untuk error autentikasi atau validasi. Cuplikan ini berfungsi tanpa perubahan baik langsung ke Anthropic maupun pada endpoint apa pun yang kompatibel dengan OpenAI:

backoff.py

import time, random
from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://api.kunavo.com/v1", api_key="sk-kn-...")

def with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise                      # don't retry auth/validation errors
            retry_after = e.response.headers.get("retry-after")
            delay = float(retry_after) if retry_after else min(2 ** attempt, 30)
            time.sleep(delay + random.uniform(0, 0.5))   # jitter avoids herds
    raise RuntimeError("retries exhausted")

resp = with_backoff(lambda: client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "ping"}],
    max_tokens=32,
))
print(resp.choices[0].message.content)

Kurangi token, bukan hanya jumlah permintaan

Jika pesan menyebutkan batas token, backoff saja tidak akan menyelamatkan Anda. Kurangi potongan yang diambil, batasi max_tokens, dan aktifkan prompt caching — system prompt besar yang stabil dengan 10% dari laju input juga mengurangi tekanan pada ITPM.

Jika Anda melakukan panggilan melalui Kunavo

Memanggil Claude melalui Kunavo tidak secara ajaib menghapus batas laju, tetapi mengubah dampak ekonomi dari kegagalan: permintaan yang gagal (termasuk 429) tidak pernah ditagihkan, dan dasbor penggunaan per kunci menunjukkan dengan tepat kunci serta model mana yang mengalami lonjakan sehingga Anda dapat meratakannya. Cuplikan backoff di atas tetap dapat digunakan apa adanya — hanya base_url yang berbeda. Batas laju adalah batas throughput, bukan harga — untuk mengetahui biaya panggilan Claude sebenarnya per 1M token, dengan daftar harga resmi Anthropic di samping harga kami, lihat Daftar harga Claude API Anthropic.

Pertanyaan umum

Apakah meningkatkan tingkat penggunaan Anthropic saya menghilangkan error 429?

Tingkat yang lebih tinggi meningkatkan batas per menit, sehingga 429 lebih jarang terjadi, tetapi lonjakan dapat mencapai batas tetap apa pun. Kode produksi tetap memerlukan backoff, terlepas dari tingkatnya.

Haruskah saya langsung melakukan retry setelah 429?

Tidak — patuhi header retry-after (atau gunakan backoff eksponensial dengan jitter jika header tersebut tidak ada). Retry langsung memperpanjang jendela pembatasan laju dan dapat berkembang menjadi penguncian yang lebih lama.

Apakah permintaan 429 yang gagal membutuhkan biaya?

Anthropic tidak mengenakan biaya untuk permintaan yang ditolak, begitu pula Kunavo — permintaan yang gagal tidak pernah ditagihkan. Biaya 429 adalah latensi, bukan uang.

Panduan terkait

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