Error 429 rate_limit_error di API Claude — arti dan cara mengatasinya

429 adalah kesalahan yang berarti "perlahankan", bukan "uang Anda habis". Perbedaannya penting: solusi yang satu adalah menunggu, sedangkan solusi yang lain adalah mengisi ulang saldo — dan mencampuradukkan keduanya dapat menyebabkan berjam-jam debugging di tempat yang salah.

Error

respons (HTTP 429)

{
  "type": "error",
  "error": { "type": "rate_limit_error",
             "message": "Number of requests has exceeded your rate limit" }
}

Ringkasan penyebab dan perbaikan

Penyebab	Perbaikan
Permintaan per menit melebihi batas akun Anda	Antrekan permintaan dan batasi konkurensi di klien, alih-alih mengirim semuanya sekaligus.
Token per menit melebihi batas	Prompt panjang menghabiskan kuota token jauh lebih cepat daripada kuota permintaan. Kurangi konteks atau bagi pekerjaan menjadi beberapa bagian.
Beberapa proses menggunakan kunci yang sama	Batas berlaku untuk kunci, bukan proses. Worker paralel dijumlahkan terhadap kuota yang sama.
Retry tanpa backoff	Mengulangi segera membuat Anda terus-menerus berada di atas batas. Backoff eksponensial dengan jitter wajib digunakan.

Patuhi retry-after jika tersedia

Jika respons menyertakan header retry-after, itu bukan saran: itulah waktu tepat setelah permintaan kembali diterima. Menunggu lebih singkat pasti menghasilkan 429 lagi.

retry_after.py

import time
from openai import APIStatusError

try:
    resp = client.chat.completions.create(model=MODELO, messages=msgs)
except APIStatusError as e:
    if e.status_code == 429:
        espera = float(e.response.headers.get("retry-after", 5))
        time.sleep(espera)
        resp = client.chat.completions.create(model=MODELO, messages=msgs)
    else:
        raise

Batasi konkurensi sejak sumbernya

Penyebab yang paling umum bukan volume total, melainkan lonjakan: dua puluh permintaan yang dikirim pada saat yang sama dapat melampaui batas yang tidak dilampaui oleh enam puluh permintaan yang tersebar selama satu menit. Semaphore mengatasi hal yang tidak dapat diatasi oleh retry saja.

concorrencia.py

import asyncio

LIMITE = asyncio.Semaphore(4)   # no máximo 4 chamadas simultâneas

async def chamar(msgs):
    async with LIMITE:
        return await client.chat.completions.create(
            model=MODELO, messages=msgs)

Pastikan ini batas laju, bukan saldo

429 tidak pernah berarti kredit habis — itu adalah 402. Jika log Anda mencampur keduanya, pisahkan berdasarkan status sebelum menyelidiki: solusi untuk 429 adalah penjadwalan, sedangkan solusi untuk 402 adalah pengisian ulang. Mengulangi 402 akan selalu gagal.

Jika Anda melakukan panggilan melalui Kunavo

Di Kunavo, batas berlaku per kunci dan saldo merupakan dompet prabayar terpisah, sehingga kedua kasus muncul dengan status berbeda: 429 untuk batas laju dan 402 ketika saldo tidak mencukupi untuk panggilan — tidak pernah salah satunya menyamar sebagai yang lain. Permintaan yang ditolak tidak dikenai biaya. Tarif per token, yang menentukan jumlah saldo yang dikonsumsi setiap panggilan, tersedia di panduan harga API Claude kami.

Pertanyaan umum

Apakah 429 berarti kredit saya habis?

Tidak. Saldo yang tidak mencukupi adalah 402. 429 berkaitan dengan kecepatan: Anda mengirim terlalu banyak permintaan atau token dalam waktu singkat, dan menunggu akan menyelesaikannya.

Berapa lama saya harus menunggu?

Jika header retry-after tersedia, tunggu tepat selama waktu tersebut. Jika tidak, gunakan backoff eksponensial mulai dari 1–2 detik dengan jitter, hingga batas 30–60 detik.

Apakah menaikkan batas akan menyelesaikan masalah?

Ini membantu jika volumenya memang sangat tinggi, tetapi sebagian besar 429 berasal dari lonjakan singkat. Membatasi konkurensi biasanya menyelesaikan masalah tanpa mengubah batas apa pun.

Panduan terkait

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