Error 429 di API AI, Penyebab dan Cara Mengatasinya

Error 429 (Too Many Requests) di API AI artinya permintaanmu ditolak sementara karena melewati salah satu batas akun: jumlah permintaan, jumlah token, atau batas belanja.

Kenapa ini penting? Aplikasi yang tidak siap menghadapi 429 akan gagal tepat saat paling ramai dipakai, misalnya ketika chatbot sedang melayani banyak pelanggan atau saat proses massal berjalan. Cara menanganinya juga berbeda tergantung jenis 429-nya. Mengulang permintaan bisa menyelesaikan satu jenis, tetapi justru memperparah jenis lain.

Apa saja penyebab error 429?

Berdasarkan dokumentasi resmi OpenAI, Anthropic, dan Google per 11 November 2026, penyebabnya bisa dikelompokkan seperti ini:

Beberapa detail yang sering terlewat. Dokumentasi Claude menyebut batas bisa diterapkan dalam interval lebih pendek, misalnya 60 RPM ditegakkan sebagai satu permintaan per detik, sehingga ledakan permintaan singkat bisa kena 429 walau total per menitnya masih di bawah batas. OpenAI menghitung pemakaian dari nilai yang lebih besar antara max_tokens dan perkiraan token permintaan, jadi max_tokens yang terlalu besar ikut menghabiskan jatah. Di Claude, max_tokens tidak dihitung untuk OTPM, dan token yang dibaca dari cache tidak dihitung untuk ITPM. Gemini menerapkan batas per proyek, bukan per API key, sehingga membuat banyak key di proyek yang sama tidak menambah jatah.

Cara membedakan jenis 429

Jangan hanya melihat kode status. Baca isi respons dan header-nya:

• Header retry-after: bila ada, ini petunjuk berapa detik harus menunggu. Anthropic menyatakan percobaan sebelum waktu itu akan gagal.
• Header sisa kuota: OpenAI mengirim x-ratelimit-remaining-requests dan x-ratelimit-remaining-tokens, Anthropic mengirim keluarga header anthropic-ratelimit-*. Dari sini kamu tahu batas mana yang habis.
• Isi pesan error: tipe dan kode error di badan respons membedakan batas sementara dari batas belanja atau kuota. Claude, misalnya, memakai kode enforced_spend_limit_reached untuk batas belanja.

Simpan header dan pesan error ini di log aplikasi. Tanpa itu, kamu hanya tahu "kena 429" tanpa tahu harus berbuat apa.

Bagaimana menulis retry yang benar?

Untuk 429 sementara, ulangi permintaan dengan jeda yang makin panjang (exponential backoff) dan sedikit acak (jitter) agar banyak proses tidak mengulang di detik yang sama. Panduan rate limit OpenAI merangkum aturan mainnya: pakai Retry-After sebagai waktu tunggu minimal lalu tambah jeda acak kecil, pakai backoff dengan jitter bila header tidak ada, batasi jumlah percobaan dan total waktu, dan jangan mengulang error kuota atau tagihan.

Contoh sederhana dalam Python, untuk dipakai dengan klien HTTP apa pun:

import random
import time

def panggil_dengan_retry(kirim, maks_percobaan=5, batas_tunggu=60):
    for percobaan in range(maks_percobaan):
        resp = kirim()
        if resp.status_code != 429:
            return resp
        if not batas_sementara(resp):   # cek kode error di badan respons
            raise RuntimeError("Batas belanja atau kuota, jangan diulang")
        retry_after = resp.headers.get("retry-after")
        if retry_after:
            tunggu = float(retry_after) + random.uniform(0, 1)
        else:
            tunggu = min(batas_tunggu, 2 ** percobaan) + random.uniform(0, 1)
        time.sleep(tunggu)
    raise RuntimeError("Masih 429 setelah beberapa percobaan")

Fungsi batas_sementara kamu tulis sesuai format error penyedia yang dipakai. SDK resmi umumnya sudah punya retry otomatis. Kalau kamu menulis retry sendiri, matikan retry bawaan SDK, karena dua lapis retry akan melipatgandakan permintaan, dan menurut OpenAI percobaan yang gagal tetap dihitung ke batas per menit.

Mencegah 429 sebelum terjadi

Retry hanya menambal. Pencegahan yang lebih awet:

• Antrekan permintaan dan atur jumlah proses paralel, jangan menembak ratusan permintaan sekaligus.
• Set max_tokens mendekati panjang jawaban yang memang dibutuhkan.
• Manfaatkan prompt caching untuk instruksi dan dokumen yang berulang. Di Claude, token yang dibaca dari cache tidak dihitung ke ITPM. Penjelasannya ada di apa itu prompt caching.
• Pisahkan batas per tim atau per aplikasi supaya satu proses massal tidak menghabiskan jatah chatbot pelanggan. Caranya dibahas di membatasi kuota dan biaya API AI per tim.
• Siapkan model cadangan. Gateway AI bisa mengalihkan permintaan ke model atau penyedia lain saat satu jalur kena batas, seperti dijelaskan di apa itu AI gateway.
• Naikkan tier akun bila pemakaian memang tumbuh. Ketiga penyedia punya sistem tier yang naik otomatis seiring riwayat pemakaian atau pembayaran, dengan syarat masing-masing.

Kenapa masih 429 padahal dashboard menunjukkan pemakaian rendah?

Ada beberapa kemungkinan. Batas mungkin diterapkan per detik sehingga ledakan singkat sudah cukup memicunya. Batas bisa berlaku di tingkat organisasi atau proyek, sehingga aplikasi lain yang memakai akun yang sama ikut menghabiskan jatah. Batas per model juga berbeda, jadi berpindah ke model lain bisa memberi hasil berbeda. Terakhir, akun baru biasanya mulai di tier dengan batas lebih rendah.