Rate Limit Itu Seperti Gerbang Tol: Arti Error 429, Bedanya dengan Kuota Harian, dan Cara Menghadapinya

Rate limit adalah batas jumlah request yang boleh dikirim ke sebuah API dalam rentang waktu tertentu, misalnya 10 request per detik. Analogi paling gampang: rate limit itu seperti gerbang tol. Mobil dilewatkan satu per satu dengan kecepatan tertentu supaya jalan di depannya tidak macet. Kalau Anda datang terlalu rapat, palang turun sebentar dan server menjawab dengan status 429.

Bagi pemula, error 429 sering terasa seperti hukuman. Padahal itu hanya rambu "tunggu sebentar". Artikel ini membahas apa arti 429, bedanya rate limit dengan kuota harian, cara server menghitung batasnya, dan cara menulis kode yang sabar supaya tidak ada request yang hilang.

Ringkasan cepat: istilah apa saja yang perlu Anda tahu?

Ada tujuh istilah yang hampir selalu muncul saat membahas rate limit, dan semuanya bisa dijelaskan dengan gerbang tol.

Istilah	Artinya	Analogi gerbang tol
Rate limit	Batas request per rentang waktu pendek, misalnya per detik	Berapa mobil boleh lewat tiap detik
Kuota	Batas total pemakaian per periode panjang, misalnya per hari	Jatah perjalanan hari ini
429 Too Many Requests	Status HTTP saat batas terlampaui	Palang turun
Retry-After	Header yang memberi tahu berapa lama harus menunggu	Papan "buka lagi 5 detik"
Burst	Lonjakan singkat yang masih ditoleransi	Rombongan kecil yang masih muat
Backoff	Menunggu makin lama di tiap percobaan ulang	Mundur, beri jarak, coba lagi
Jitter	Jeda acak kecil supaya klien tidak serempak	Tidak semua mobil tancap gas bersamaan

Apa itu rate limit dan kenapa API membutuhkannya?

Rate limit adalah aturan kecepatan yang dipasang server untuk setiap pengguna, biasanya dikenali dari API key. API key berperan seperti pelat nomor: gerbang tahu mobil mana yang lewat dan seberapa sering.

Ada tiga alasan API memasangnya. Pertama, keadilan: satu pengguna yang mengirim ribuan request sekaligus tidak boleh membuat pengguna lain ikut lambat. Kedua, perlindungan: kode yang salah, misalnya perulangan tanpa henti, tidak sampai menjatuhkan server. Ketiga, biaya: setiap request memakai CPU dan bandwidth yang harus dibayar seseorang.

Apa arti error 429 Too Many Requests?

Status 429 berarti Anda mengirim terlalu banyak request dalam waktu tertentu, bukan berarti server rusak atau akun Anda diblokir. Definisi ini berasal dari RFC 6585. Dokumen yang sama menyebut server boleh menyertakan header Retry-After untuk memberi tahu lama menunggu, tetapi tidak wajib.

Contoh respons 429 yang lengkap terlihat seperti ini:

HTTP/1.1 429 Too Many Requests
Retry-After: 5
Content-Type: application/json

{ "is_success": false, "message": "Terlalu banyak request, coba lagi sebentar." }

Nilai Retry-After bisa berupa jumlah detik seperti di atas, atau berupa tanggal dan jam. RFC 6585 juga sengaja tidak mengatur cara server mengenali pengguna dan menghitung request, sehingga tiap layanan punya aturan sendiri.

Apa bedanya rate limit dengan kuota harian?

Rate limit mengatur seberapa cepat Anda boleh lewat, sedangkan kuota mengatur seberapa banyak jatah Anda. Keduanya sering tertukar karena sama-sama membatasi, padahal cara menghadapinya berbeda.

Aspek	Rate limit	Kuota harian
Yang diukur	Kecepatan	Total pemakaian
Rentang waktu	Detik atau menit	Hari atau bulan
Pulih kapan	Dalam hitungan detik	Saat reset periode
Solusi	Tunggu sebentar, coba lagi	Hemat request, atau naikkan paket
Analogi lain	Kecepatan internet	Kuota paket data harian

Berapa batasnya di APIPedia?

APIPedia memakai dua batas itu sekaligus di setiap paket. Angka berikut kami ambil dari daftar paket (GET /v1/plans) pada 12 November 2026.

Paket	Rate limit	Kuota harian
Free	10 request per detik	500 request per hari
Pro	60 request per detik	25.000 request per hari
Enterprise	300 request per detik	250.000 request per hari

Grafik di atas menunjukkan kenapa keduanya dibutuhkan. Kalau sebuah skrip terus melaju di kecepatan maksimum, kuota Free habis dalam 50 detik, Pro dalam 6,9 menit, dan Enterprise dalam 13,9 menit. Rate limit menjaga lonjakan sesaat, kuota menjaga total pemakaian. Sisa kuota dan waktu reset bisa dicek lewat GET /v1/me/quota. Pada akun uji kami, resetAt menunjuk pukul 00.00 WIB.

Bagaimana server menghitung rate limit?

Server menghitung rate limit dengan salah satu dari empat algoritma umum, dan pilihan algoritma menentukan seberapa ramah ia terhadap lonjakan.

Algoritma	Cara kerja	Analogi
Fixed window	Hitung request per jendela waktu tetap, lalu reset ke nol	Jatah per jam yang diisi ulang tepat di menit 00
Sliding window	Hitung request dalam rentang waktu yang bergeser terus	Petugas melihat 60 detik terakhir, kapan pun Anda datang
Token bucket	Tiap request mengambil satu koin dari ember yang diisi ulang pelan-pelan	Ember koin di loket
Leaky bucket	Request masuk antrean dan dilayani dengan kecepatan tetap	Corong: dituang deras, keluarnya tetap menetes

Token bucket: ember koin

Token bucket bekerja seperti ember berisi koin. Setiap request mengambil satu koin. Ember diisi ulang dengan kecepatan tetap dan tidak bisa melebihi kapasitasnya. Selama masih ada koin, request lolos, sehingga lonjakan singkat tetap dilayani.

class TokenBucket:
    """Ember koin: tiap request mengambil 1 koin, koin diisi ulang terus-menerus."""
    def __init__(self, kapasitas: int, isi_per_detik: float):
        self.kapasitas, self.laju = kapasitas, isi_per_detik
        self.koin, self.terakhir = float(kapasitas), 0.0

    def izinkan(self, sekarang: float):
        # isi ulang sesuai waktu yang berlalu, tapi tidak melebihi kapasitas
        self.koin = min(self.kapasitas, self.koin + (sekarang - self.terakhir) * self.laju)
        self.terakhir = sekarang
        if self.koin >= 1:
            self.koin -= 1
            return True, 0.0                       # 200 OK
        return False, (1 - self.koin) / self.laju  # 429 + Retry-After (detik)

Kami menjalankan simulasi dengan ember berkapasitas 10 koin yang diisi 10 koin per detik, lalu mengirim 30 request dalam 1 detik. Ini ilustrasi konsep, bukan gambaran implementasi internal layanan mana pun.

A tanpa jeda : ##############x#xx#xx#xx#xx#xx | lolos 19 ditolak 11
B patuh      : lolos 30 dari 30, kena 429 16 kali, selesai dalam 2.0 detik

Pada skenario A, 14 request pertama lolos karena ember masih penuh dan terus terisi. Setelah itu hanya request yang kebagian koin baru yang lolos, dan 11 request hilang. Pada skenario B, klien menunggu setiap kali ditolak. Hasilnya, 30 request selesai semua dalam 2 detik.

Apa yang sering disalahpahami tentang rate limit?

Ada enam anggapan keliru yang paling sering muncul, dan sebagian besar berasal dari rasa panik saat pertama kali melihat 429.

• "429 berarti server rusak." Bukan. Kode 4xx berarti masalahnya di sisi pengirim, dalam hal ini kecepatan kirim. Server justru sedang bekerja sesuai aturan.
• "429 berarti akun saya diblokir." Tidak. Batas kecepatan pulih sendiri dalam hitungan detik.
• "Rate limit sama dengan kuota." Berbeda. Menunggu lima detik menyelesaikan rate limit, tetapi tidak menambah kuota harian yang sudah habis.
• "Kalau ditolak, langsung kirim ulang secepatnya." Ini memperburuk keadaan. Request ulang yang terlalu cepat ikut dihitung dan ikut ditolak.
• "Header Retry-After pasti ada." Tidak selalu. Standarnya hanya menyebut "boleh", jadi kode Anda perlu rencana cadangan berupa backoff.
• "Header sisa limit sudah distandarkan." Belum. Header RateLimit dan RateLimit-Policy masih berstatus Internet-Draft di IETF (versi 11, Mei 2026). Banyak layanan masih memakai nama header sendiri, jadi selalu baca dokumentasinya.

Bagaimana cara menghadapi error 429 di kode?

Cara yang benar adalah berhenti sejenak, menunggu sesuai petunjuk server, lalu mencoba lagi dengan jeda yang makin panjang. Fungsi Python berikut memakai pustaka bawaan dan sudah kami uji terhadap server lokal yang menjawab 429 dua kali sebelum 200.

import random, time, urllib.request, urllib.error

def panggil(url: str, maks_coba: int = 5) -> bytes:
    for percobaan in range(maks_coba):
        try:
            with urllib.request.urlopen(url, timeout=10) as r:
                return r.read()
        except urllib.error.HTTPError as e:
            if e.code != 429:
                raise                                   # error lain: jangan diulang membabi buta
            retry_after = e.headers.get("Retry-After")
            if retry_after and retry_after.isdigit():
                tunggu = int(retry_after)               # patuhi papan pengumuman server
            else:
                tunggu = min(30, 2 ** percobaan)        # backoff: 1, 2, 4, 8 ... detik
            tunggu += random.uniform(0, 0.5)            # jitter: supaya klien tidak serempak
            print(f"429, tunggu {tunggu:.1f} detik (percobaan {percobaan + 1})")
            time.sleep(tunggu)
    raise RuntimeError("Masih 429 setelah beberapa percobaan")

Hasil ujinya:

429, tunggu 1.3 detik (percobaan 1)
429, tunggu 1.5 detik (percobaan 2)
b'{"ok":true}'

Tiga hal penting di kode itu. Pertama, hanya 429 yang diulang. Kedua, Retry-After didahulukan, dan backoff dipakai kalau header itu tidak ada. Ketiga, ada batas percobaan supaya kode tidak menunggu selamanya. Contoh ini hanya membaca Retry-After berbentuk detik. Kalau layanan Anda mengirim bentuk tanggal, tambahkan penguraian tanggalnya.

Tips praktis supaya jarang kena rate limit

Tujuh kebiasaan berikut membuat aplikasi Anda jarang menyentuh batas, baik batas kecepatan maupun kuota.

1. Simpan hasil yang jarang berubah. Daftar provinsi, hari libur, atau kurs harian tidak perlu diminta ulang tiap kali halaman dibuka. Cache menghemat kuota paling besar.
2. Batasi kecepatan di sisi Anda sendiri. Beri jeda antar-request di skrip massal, sedikit di bawah batas paket.
3. Pakai antrean untuk pekerjaan besar. Ribuan data lebih aman diproses bertahap daripada sekaligus.
4. Tangani 429 dengan backoff dan jitter seperti contoh di atas.
5. Pantau pemakaian. Cek sisa kuota secara berkala. Di APIPedia, paket Pro ke atas menyediakan alert kuota.
6. Jangan membagi satu API key ke banyak aplikasi. Semua aplikasi itu akan berebut batas yang sama, dan sumber lonjakan sulit dilacak.
7. Naikkan paket bila memang kebutuhan. Kalau setelah dihemat kuota tetap habis tiap hari, itu tanda aplikasi Anda tumbuh.

Pertanyaan yang sering diajukan

Berapa lama harus menunggu setelah kena 429?

Ikuti nilai header Retry-After bila ada. Kalau tidak ada, mulai dari 1 detik lalu gandakan di tiap percobaan (1, 2, 4, 8 detik) dengan batas atas, misalnya 30 detik.

Apakah request yang ditolak 429 mengurangi kuota harian?

Tergantung layanannya, karena standar HTTP tidak mengatur cara menghitung. Cara paling aman adalah mengecek angka pemakaian sebelum dan sesudah, lalu merancang kode supaya jarang ditolak sejak awal.

Kenapa saya kena 429 padahal baru mengirim sedikit request?

Biasanya karena request dikirim bersamaan. Sepuluh request paralel dalam satu kedipan sudah menyentuh batas 10 per detik. Penyebab lain: API key yang sama dipakai aplikasi atau rekan lain, atau kuota harian memang sudah habis.

Apakah rate limit berlaku per API key atau per alamat IP?

Keduanya mungkin. Layanan yang memakai API key umumnya menghitung per kunci atau per akun, sedangkan endpoint publik tanpa kunci sering menghitung per alamat IP. Dokumentasi tiap layanan yang menentukan.

Apakah model AI juga punya rate limit?

Ya. API model AI biasanya membatasi jumlah request dan jumlah token per menit. Di AI Gateway APIPedia, model gratis bisa dipakai tanpa kredit dengan batas jumlah request harian per pengguna.

Ingin mencoba model gratis yang punya batas harian? Baca cara pakai model AI Bansos di APIPedia. Batas pemakaian juga menjadi rem darurat saat kunci bocor, seperti dibahas di artikel LLMjacking: API key AI dicuri.

Sumber

• RFC 6585: Additional HTTP Status Codes (429 Too Many Requests)
• RFC 9110: HTTP Semantics (header Retry-After)
• IETF: RateLimit header fields for HTTP (Internet-Draft)
• MDN Web Docs: Retry-After