AI API Rate Limiting: Cara Kerja dan Cara Menanganinya

Respons 429 dari AI API bisa berarti empat hal berbeda: terlalu banyak permintaan per menit, terlalu banyak token per menit, terlalu banyak koneksi konkuren, atau saldo akun habis. Keempatnya mengembalikan kode status yang sama, jadi solusinya bergantung pada diagnosis batasan mana yang sebenarnya Anda capai, bukan sekadar mencoba lagi dengan lebih agresif. Panduan ini menguraikan mode kegagalan, menunjukkan bukti apa yang tersedia dan tidak tersedia mengenai batasan saat ini, serta memberikan pola percobaan ulang (retry) dan fallback yang tangguh untuk produksi.

Poin Penting

• Kode 429 bisa berarti batas permintaan, anggaran token, batas konkurensi, atau saldo akun yang habis. Masing-masing memerlukan solusi berbeda, dan percobaan ulang secara membabi buta hanya menyelesaikan satu dari empat masalah tersebut.
• Baca header rate-limit pada respons yang berhasil, bukan hanya setelah terjadi error, dan lakukan throttling sebelum Anda mendekati batas maksimal.
• Penghitungan token di sisi klien hanyalah estimasi, bukan jaminan. Ketidakcocokan tokenizer antara pustaka Anda dan penghitungan aktual penyedia dapat membuat margin keamanan lebih sempit dari yang Anda kira.
• Batas RPM/TPM yang tepat per model dan tier tidak dipublikasikan dalam bukti yang tersedia untuk artikel ini. Anggap angka apa pun yang Anda lihat di tempat lain sebagai sesuatu yang harus diverifikasi terhadap dasbor akun Anda sendiri, bukan konstanta tetap.
• Percobaan ulang yang tangguh memerlukan exponential backoff, jitter, jumlah percobaan ulang maksimal, dan kepatuhan terhadap header retry-after. Jangan pernah mencoba ulang operasi non-idempotent secara membabi buta.

Memahami AI API Rate Limiting: Empat Mode Kegagalan

Batas permintaan

Sebagian besar penyedia menghitung permintaan per menit (RPM). Jika terlampaui, Anda akan mendapatkan 429 instan, sering kali dengan badan respons kosong. Pengguna yang melakukan paging hasil dengan cepat, atau cron job yang berjalan tanpa throttle, adalah pemicu umum.

Batas token

Ini adalah jebakan yang paling sering diremehkan oleh tim. Penyedia sering kali menerapkan token per menit (TPM) secara terpisah dari RPM, sehingga Anda bisa terkena 429 meskipun masih berada di bawah batas permintaan Anda. Model dengan konteks besar memperburuk hal ini: berdasarkan bukti harga langsung TokenLab (diamati 2026-07-07), Claude Opus 4.8 dan GPT-5.5 mendukung sekitar 1.000.000+ token konteks. Panggilan yang memuat dokumen besar, basis kode penuh, atau riwayat obrolan panjang ke dalam jendela tersebut dapat menghabiskan sebagian besar anggaran token per menit Anda dalam satu permintaan, meskipun itu hanya "satu" permintaan. Ini adalah risiko perencanaan kapasitas berdasarkan ukuran jendela konteks, bukan jumlah token per panggilan yang terukur, jadi validasikan penggunaan aktual terhadap log Anda sendiri daripada berasumsi dengan angka tetap.

Batas konkurensi

Penyedia mungkin menoleransi volume rata-rata per menit Anda sampai Anda membuka lima puluh stream sekaligus. Batas konkurensi membatasi permintaan atau koneksi yang sedang berlangsung secara bersamaan. Respons streaming menahan koneksi tetap terbuka lebih lama, yang menghabiskan slot konkurensi lebih cepat daripada panggilan singkat sekali jalan. Agen pengodean yang dibangun di atas Claude Sonnet 5 atau Kimi K2.7 Code, dan antarmuka suara yang melakukan streaming dari Gemini 3.5 Flash, adalah pemicu umum karena mereka menjaga banyak koneksi jangka panjang tetap terbuka sekaligus.

Kuota atau kehabisan saldo

Ini terlihat identik dengan rate limit di dasbor Anda: panggilan berhenti berfungsi. Namun, solusinya berbeda. Jika akun Anda kehabisan kredit prabayar atau mencapai batas pengeluaran harian yang ketat, API mengembalikan error yang menyerupai rate limit. Backoff tidak ada gunanya di sini. Anda perlu menambah saldo atau menaikkan ambang batas pengeluaran.

Snapshot Sumber

Poin data	Sumber	Diamati pada
Jendela konteks model dan harga per token	Bukti harga/model langsung TokenLab	2026-07-07
Penamaan SSOT model (Claude Sonnet 5, GPT-5.5, Gemini 3.5 Flash, dll.)	SSOT model TokenLab	2026-07-07, kedaluwarsa 2026-07-14
Batas tier RPM/TPM penyedia resmi	Tidak tersedia dalam set bukti ini	Tidak diverifikasi, periksa dasbor akun penyedia
Perilaku normalisasi header gateway TokenLab	Tidak tersedia dalam set bukti ini	Verifikasi di dokumentasi API TokenLab sebelum mengandalkan skema header tunggal

Jendela Konteks Model dan Harga Saat Ini (Bukti Langsung TokenLab)

Angka-angka ini berasal langsung dari snapshot harga langsung TokenLab. Ini bukan batas RPM atau TPM, melainkan menunjukkan mengapa satu panggilan pada model dengan konteks besar dapat menghabiskan anggaran token secara tidak proporsional.

Model	Penyedia	Jendela Konteks	Input $/MTok	Output $/MTok	Sumber	Diamati
Claude Sonnet 5	Anthropic	1.000.000	$2.00	$10.00	Bukti harga langsung TokenLab	2026-07-07
Claude Opus 4.8	Anthropic	1.000.000	$5.00	$25.00	Bukti harga langsung TokenLab	2026-07-07
Claude Fable 5	Anthropic	1.000.000	$10.00	$50.00	Bukti harga langsung TokenLab	2026-07-07
GPT-5.5	OpenAI	1.050.000	$5.00	$30.00	Bukti harga langsung TokenLab	2026-07-07
GPT-5.5 Batch/Flex	OpenAI	1.050.000	$2.50	$15.00	Bukti harga langsung TokenLab	2026-07-07
Gemini 3.5 Flash	Google	1.048.576	$1.50	$9.00	Bukti harga langsung TokenLab	2026-07-07
GLM-5.2	Z.ai	1.048.576	$0.93	$3.00	Bukti harga langsung TokenLab	2026-07-07
Kimi K2.7 Code	Moonshot AI	262.144	$0.74	$3.50	Bukti harga langsung TokenLab	2026-07-07
DeepSeek V4 Pro	DeepSeek	1.048.576	$0.44	$0.87	Bukti harga langsung TokenLab	2026-07-07
DeepSeek V4 Flash	DeepSeek	1.048.576	$0.09	$0.18	Bukti harga langsung TokenLab	2026-07-07
Qwen3.7 Plus	Alibaba	1.000.000	$0.32	$1.28	Bukti harga langsung TokenLab	2026-07-07
MiniMax M3	MiniMax	1.048.576	$0.30	$1.20	Bukti harga langsung TokenLab	2026-07-07

Catatan SSOT model: nama-nama ini mencerminkan SSOT model TokenLab yang diamati pada 2026-07-07, kedaluwarsa 2026-07-14. Penamaan dan ketersediaan sering berubah. Sebelum Anda melakukan hardcode string model ke dalam kode produksi, pastikan model tersebut masih terdaftar di direktori model TokenLab atau papan peringkat model.

Memperbaiki Kegagalan Rate Limit Tanpa Membangun Logika Percobaan Ulang dari Awal

Semua hal di atas adalah diagnosis. Pekerjaan remediasi, memutuskan model mana yang akan digunakan sebagai fallback, melacak konkurensi per pengguna, dan menjaga gambaran langsung tentang keluarga model mana yang sehat, adalah hal yang dirancang untuk ditangani oleh lapisan perutean TokenLab. Alih-alih membuat matriks fallback sendiri di lima penyedia, Anda mengarahkan permintaan ke TokenLab dan membiarkan gateway memilih di antara katalog model saat ini berdasarkan ketersediaan dan aturan fallback Anda.

Satu catatan jujur: TokenLab berada di depan beberapa penyedia upstream, dan masing-masing upstream mengembalikan set header, format error, dan semantik percobaan ulangnya sendiri. Apakah gateway menormalisasi sepenuhnya setiap header rate-limit menjadi satu skema yang konsisten, atau meneruskan beberapa header upstream tanpa perubahan, tidak dikonfirmasi dalam bukti yang tersedia untuk artikel ini. Verifikasi perilaku header saat ini di dokumentasi API TokenLab sebelum Anda menulis logika parsing yang mengasumsikan skema terpadu tunggal di setiap model. Bangun parser header Anda secara defensif, memeriksa keberadaan setiap bidang daripada berasumsi bahwa bidang tersebut ada.

Membaca Header Rate-Limit

Penyedia mengembalikan informasi rate-limit dalam header respons, meskipun nama pastinya bervariasi tergantung penyedia. Pola umum terlihat seperti ini:

x-ratelimit-limit-requests: 500
x-ratelimit-remaining-requests: 499
x-ratelimit-reset-requests: 12s
retry-after: 0

Baca ini pada respons yang berhasil, bukan hanya setelah 429. Simpan hitungan bergulir dari anggaran yang tersisa dan perlambat saat Anda turun di bawah ambang batas keamanan, biasanya 10-20% headroom, meskipun angka yang tepat bergantung pada burstiness lalu lintas Anda dan bukan sesuatu yang dapat ditentukan oleh set bukti ini untuk Anda.

Logika Percobaan Ulang Dengan Penanganan Error Eksplisit

Pembantu percobaan ulang perlu menangani lebih dari sekadar kasus 429. Ia harus membedakan error transien (429, 503, timeout) dari error klien (4xx selain 429) yang tidak akan pernah berhasil jika dicoba ulang, dan harus mematuhi retry-after jika ada.

async function callWithRetry(fn, maxRetries = 4) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const status = err.status;

      // Error klien selain 429 tidak akan berhasil jika dicoba ulang
      if (status && status >= 400 && status < 500 && status !== 429) {
        throw err;
      }

      // Berhenti setelah percobaan ulang maksimal terlepas dari jenis error
      if (attempt === maxRetries) throw err;

      // 429: patuhi retry-after jika ada, jika tidak lakukan backoff dengan jitter
      if (status === 429) {
        const retryAfter = parseRetryAfterHeader(err);
        const delay = retryAfter
          ? retryAfter * 1000
          : Math.pow(2, attempt) * 1000 + Math.random() * 1000;
        await sleep(delay);
        continue;
      }

      // 503 atau timeout jaringan: backoff dan coba ulang, catat untuk observabilitas
      if (status === 503 || err.code === 'ETIMEDOUT' || err.code === 'ECONNRESET') {
        await sleep(Math.pow(2, attempt) * 1000 + Math.random() * 1000);
        continue;
      }

      // 5xx tidak dikenal: coba ulang dengan backoff, batasi percobaan dengan ketat
      if (status && status >= 500) {
        await sleep(Math.pow(2, attempt) * 1000 + Math.random() * 1000);
        continue;
      }

      throw err;
    }
  }
}

Jangan pernah membungkus operasi non-idempotent, seperti tagihan pembayaran atau penulisan dengan efek samping, dalam loop percobaan ulang yang naif. Konfirmasikan idempotensi atau gunakan kunci idempotensi sebelum mencoba ulang panggilan tersebut.

Akurasi Estimasi Token: Mengapa Hitungan Lokal Berbeda dari Hitungan Penyedia

Pustaka penghitungan token sisi klien memperkirakan tokenizer yang sebenarnya digunakan oleh model tertentu. tiktoken sangat cocok dengan keluarga OpenAI tetapi tidak dijamin cocok dengan tokenizer Anthropic, Google, atau open-weight secara tepat. Perbedaan muncul di sekitar token khusus, karakter multi-byte, dan pemformatan prompt sistem, dan perbedaan tersebut terakumulasi dalam percakapan panjang.

Langkah praktis untuk mengurangi penyimpangan:

• Baca penggunaan token aktual yang dikembalikan dalam badan respons (sebagian besar penyedia menyertakan jumlah token prompt dan penyelesaian) dan gunakan itu untuk mengkalibrasi estimator lokal Anda dari waktu ke waktu.
• Simpan margin keamanan, bukan batas yang kaku. Jika batas TPM penyedia Anda mendekati estimasi penggunaan Anda, tunda atau bagi permintaan daripada mengirimkannya tepat di batas tersebut.
• Jika prompt Anda besar atau berulang di seluruh panggilan, lihat cakupan TokenLab mengenai perilaku tokenisasi dan strategi pemisahan prompt untuk cara konkret memotong token per permintaan sebelum Anda mencapai batas sama sekali. Mengurangi token per panggilan sering kali merupakan solusi yang lebih murah daripada menegosiasikan tier yang lebih tinggi.

Traffic Shaping dan Model Fallback

Exponential backoff dengan jitter. Gandakan waktu tunggu setelah setiap percobaan ulang dan tambahkan jitter acak agar klien konkuren tidak mencoba ulang secara bersamaan.

Traffic shaping per pengguna atau tugas. Batasi panggilan konkuren per pengguna (misalnya, 3 konkuren, 5 permintaan per detik burst) agar satu pengguna berat tidak menghabiskan batas seluruh akun Anda dan menurunkan performa pengguna lain.

Estimasi anggaran token sebelum mengirim. Hitung token di sisi klien, dan jika permintaan akan mendorong Anda melebihi anggaran TPM yang dilacak, tunda atau bagi permintaan tersebut daripada mengirimkannya dan berharap berhasil.

Model fallback sebagai jaring pengaman. Ketika model utama mengembalikan 429, arahkan ke model alternatif dengan batasan terpisah dan kemampuan yang sebanding. Tugas pengodean dapat melakukan failover dari Claude Sonnet 5 ke DeepSeek V4 Pro atau Kimi K2.7 Code. Beban kerja bervolume tinggi dan berbiaya rendah dapat melakukan failover antara DeepSeek V4 Flash, Gemini 3.5 Flash, dan Qwen3.7 Plus, yang semuanya berada di tier perutean berbiaya rendah dari katalog model saat ini.

Daftar Periksa Penanganan Rate Limit

Kategori	Apa yang harus diperiksa	Tindakan segera	Solusi jangka panjang
Batas permintaan	Nilai header RPM, frekuensi burst	Throttling permintaan klien, tambahkan rate limiter lokal	Tier per pengguna, antrean sisi server
Batas token	Anggaran TPM per model, rata-rata token per panggilan, penggunaan yang dilaporkan respons	Pra-hitung token, bagi prompt besar, tunda panggilan di dekat batas	Batching dengan penganggaran token, arahkan pekerjaan bervolume tinggi ke model berbiaya lebih rendah
Batas konkurensi	Maksimal stream atau koneksi simultan	Batasi permintaan konkuren per klien, tutup stream yang idle	Connection pooling, peluncuran stream yang diatur
Kuota / saldo	Saldo akun, batas pengeluaran harian	Tambah kredit, sesuaikan ambang batas pengeluaran	Peringatan saldo rendah, isi ulang otomatis prabayar

Rentang Batas Tipikal: Apa yang Bisa dan Tidak Bisa Kami Konfirmasi

Pencarian sekunder untuk topik ini sering kali menginginkan tabel angka RPM/TPM "tipikal". Kami tidak akan mengada-ada. Batas per-tier yang dipublikasikan sering berubah, bervariasi menurut riwayat akun dan tier penggunaan, dan bukan bagian dari bukti yang tersedia untuk artikel ini.

Pertanyaan	Status	Langkah verifikasi
Berapa batas RPM "tipikal" untuk model frontier?	Tidak dikonfirmasi dalam set bukti ini	Periksa dasbor akun penyedia Anda atau header respons rate-limit secara langsung
Berapa batas TPM "tipikal" untuk model konteks 1M?	Tidak dikonfirmasi dalam set bukti ini	Catat penggunaan aktual dari header respons selama seminggu lalu lintas untuk membangun baseline Anda sendiri
Apakah tier penggunaan mengubah angka-angka ini?	Masuk akal berdasarkan perilaku penyedia umum, tidak di-benchmark di sini	Konfirmasikan batas tier saat ini di konsol penyedia Anda
Apakah batas agregat TokenLab cocok dengan batas penyedia upstream secara tepat?	Tidak dikonfirmasi dalam set bukti ini	Verifikasi di dokumentasi API TokenLab sebelum perencanaan kapasitas

Batasan

• Tidak ada angka RPM/TPM resmi yang tersedia untuk GPT-5.5, Claude Opus 4.8, Gemini 3.5 Flash, atau model lain yang dirujuk di sini. Setiap angka dalam tabel harga di atas adalah ukuran jendela konteks dan biaya per token, bukan rate limit.
• Apakah gateway TokenLab menyatukan header rate-limit sepenuhnya di seluruh penyedia upstream, atau meneruskan beberapa header tanpa perubahan, tidak dikonfirmasi dalam set bukti ini. Anggap parsing header sebagai sesuatu yang spesifik untuk penyedia sampai Anda memverifikasi perilaku gateway saat ini di dokumentasi.
• Nama model dalam artikel ini mencerminkan SSOT model TokenLab yang diamati 2026-07-07, kedaluwarsa 2026-07-14. Konfirmasikan ketersediaan saat ini di direktori model sebelum merilis kode yang melakukan hardcode string model.
• Akurasi estimasi token dibandingkan dengan penghitungan sisi penyedia tidak di-benchmark dalam set bukti ini. Kalibrasi estimator Anda sendiri terhadap penggunaan yang dilaporkan respons daripada mempercayai offset tetap.

FAQ

Mengapa aplikasi saya mendapatkan error 429 meskipun jumlah permintaan di bawah batas? Periksa anggaran token-per-menit (TPM) terlebih dahulu. Satu prompt besar dapat menghabiskan jatah token sementara jumlah permintaan tetap rendah. Periksa juga konkurensi: koneksi streaming yang terbuka dapat memblokir permintaan baru bahkan ketika RPM dan TPM keduanya terlihat baik-baik saja.

Haruskah saya mencoba ulang segera ketika menerima 429? Tidak. Tunggu periode yang ditentukan dalam retry-after, atau gunakan exponential backoff dengan jitter jika header tersebut tidak ada. Percobaan ulang segera berisiko menyebabkan efek thundering-herd dan dapat memperpanjang jendela lockout Anda.

Bagaimana saya tahu jika jumlah token lokal saya akan cocok dengan apa yang sebenarnya ditagihkan oleh penyedia? Anda tidak bisa tahu secara pasti. Tokenizer sisi klien adalah perkiraan. Baca penggunaan token yang dikembalikan dalam setiap badan respons dan gunakan untuk mengkalibrasi estimator Anda dari waktu ke waktu, serta simpan margin keamanan daripada mengirim permintaan tepat di batas estimasi Anda.

Apakah TokenLab mengekspos satu set header rate-limit terpadu di setiap model? Tidak dikonfirmasi dalam bukti yang tersedia di sini. Penyedia upstream yang berbeda mengembalikan format header yang berbeda, dan seberapa banyak normalisasi yang diterapkan TokenLab adalah sesuatu yang harus diverifikasi dalam dokumentasi API saat ini daripada berasumsi.

Bagaimana saya bisa menghindari rate limit tanpa meningkatkan paket saya? Kombinasikan penganggaran token, batas konkurensi lokal, dan model fallback. Estimasi token sebelum mengirim, bagi prompt panjang, dan arahkan ke model alternatif, misalnya dari Claude Sonnet 5 ke DeepSeek V4 Pro, ketika batas utama Anda tercapai.

Memulai

Rate limit adalah fakta dalam membangun AI API, tetapi tidak harus menyebabkan pemadaman. Gateway TokenLab memberi Anda akses ke katalog model saat ini serta data harga dan throughput langsung sehingga Anda dapat merutekan di sekitar batasan alih-alih menebak-nebak. Jika Anda juga mengevaluasi trade-off agregator, perbandingan OpenRouter membahas perilaku fallback dan overhead operasional secara lebih mendalam. Dapatkan kunci API Anda di tokenlab.sh dan bangun logika percobaan ulang dan fallback sekali saja, bukan per penyedia.