Batas permintaan API LLM: Tangani 429, Percobaan ulang, dan Konkurensi dengan Aman

Aplikasi LLM produksi butuh lebih dari sekadar loop percobaan ulang. Aplikasi itu perlu tahu kenapa sebuah permintaan ditolak, berapa banyak beban yang bisa diterima, dan kapan harus berhenti mencoba.

Titik awal yang praktis itu sederhana: klasifikasikan error, kendalikan penerimaan permintaan, dan coba ulang hanya kegagalan yang masuk akal bisa pulih dalam tenggat waktu operasi. Menambah percobaan ulang tanpa kontrol ini bisa mengubah lonjakan trafik kecil jadi gangguan yang lebih lama.

Panduan ini membahas desain aplikasi yang netral penyedia. Kuota, kode error, header, dan aturan penghitungan yang tepat bergantung pada penyedia, model, akun, dan gateway kamu.

Pahami batas mana yang kamu capai

Kontrol-kontrol ini menjawab pertanyaan yang berbeda:

Kontrol	Apa yang diukur	Respons aplikasi
Batas permintaan	Permintaan yang diterima dalam jendela waktu	Atur laju awal dan haluskan lonjakan
Batas token	Pemakaian token atau perkiraan kebutuhan token	Cadangkan kapasitas token dan batasi ukuran permintaan
Konkurensi	Permintaan yang sedang berjalan	Batasi worker atau pakai semaphore
Pengeluaran atau saldo	Ketersediaan finansial	Cek kontrol pembayaran atau anggaran

OpenAI, misalnya, mendokumentasikan batas permintaan dan token secara terpisah, dengan cakupan yang bisa mencakup proyek dan keluarga model bersama. Jadi API key baru belum tentu berarti kapasitas baru. Dokumentasinya juga membedakan error batas permintaan sementara dari batas pengeluaran keras, meskipun keduanya memakai 429. Baca isi error-nya, jangan mengambil keputusan hanya dari status. Dokumentasi batas permintaan OpenAI

Standar HTTP mendefinisikan 429 tapi tidak mengatur bagaimana sebuah layanan mengidentifikasi pemanggil atau menghitung permintaan. Standar itu juga membuat Retry-After opsional. Jangan berasumsi setiap endpoint yang kompatibel dengan OpenAI punya perilaku pembatasan yang sama. Spesifikasi HTTP 429

Ukur trafik di sekitar batasan yang lebih ketat

Bayangkan contoh sederhana dan hipotetis: jatah 60 permintaan per menit dan 120,000 token per menit. Kalau setiap permintaan memakai 4,000 token yang dihitung, kapasitas token hanya mendukung 30 permintaan seperti itu per menit:

120,000 tokens/minute ÷ 4,000 tokens/request = 30 requests/minute

Ini contoh perencanaan, bukan kuota penyedia atau penjadwal yang pasti. Sebuah layanan bisa mencadangkan perkiraan output, memakai jendela penegakan yang lebih pendek, atau menghitung kategori token yang berbeda secara berbeda.

Ukur distribusi ukuran permintaanmu sendiri. Rata-rata saja menyembunyikan unggahan dokumen besar dan generasi panjang. Sisakan ruang untuk outlier ini, jangan menargetkan angka maksimum matematis.

Pakai kontrol terpisah untuk awal permintaan dan pekerjaan yang sedang berjalan. Batas konkurensi saja tidak menegakkan permintaan per menit: respons cepat bisa membebaskan slot cukup cepat untuk menciptakan awal permintaan yang berlebihan. Sebaliknya, pembatas laju permintaan tidak menghentikan streaming lambat menumpuk dan menghabiskan koneksi.

Taruh kontrol penerimaan sebelum percobaan ulang

Jalur permintaan yang berguna adalah:

Authenticated request → bounded queue → rate/token admission → worker → provider

Rancang antreannya dengan sengaja:

• Tetapkan panjang antrean maksimum dan waktu tunggu maksimum.
• Beri permintaan interaktif tenggat waktu yang lebih pendek daripada tugas latar belakang.
• Tolak atau tunda pekerjaan berlebih dengan respons tingkat aplikasi yang jelas.
• Hapus tugas yang dibatalkan dan kedaluwarsa sebelum dikirim.
• Bagikan status penerimaan di seluruh replika yang memakai kuota upstream yang sama.

Kalau tidak, menambah server aplikasi bisa melipatgandakan traffic sementara kapasitas upstream tetap sama. Untuk beban kerja campuran, sisihkan sebagian kapasitas untuk permintaan yang menghadap pengguna supaya tugas impor dokumen tidak mengambil semua slot.

Ini adalah rekomendasi arsitektur, bukan janji bahwa gateway tertentu menyediakan antrean atau kontrol konkurensi yang bisa diatur.

Gunakan satu kebijakan retry yang terbatas

Retry harus punya pemilik. Periksa perilaku SDK sebelum menambah loop lain. Dalam konfigurasi hipotetis, tiga percobaan aplikasi yang membungkus tiga percobaan SDK bisa menghasilkan sembilan percobaan upstream untuk satu operasi logis.

Kebijakan yang praktis adalah:

1. Klasifikasikan kegagalan menggunakan informasi error yang didokumentasikan penyedia.
2. Berhenti segera untuk error yang memerlukan perubahan kredensial, izin, pembayaran, atau konten permintaan.
3. Retry hanya kegagalan sementara yang memenuhi syarat selama anggaran percobaan dan waktu masih tersisa.
4. Patuhi panduan retry server yang valid; kalau tidak, gunakan exponential backoff dengan batas atas dan jitter.
5. Kembalikan kegagalan akhir dengan konteks yang cukup untuk menyelidikinya dengan aman.

Retry-After bisa menentukan delay atau tanggal. Perlakukan delay server yang berlaku sebagai minimum, bukan saran untuk memperpendek. Kalau melebihi tenggat waktu operasi yang tersisa, tunda pekerjaan atau gagal dengan jelas daripada retry lebih awal. Semantik HTTP Retry-After

Waktu tunggu acak mengurangi gelombang retry yang tersinkronisasi. Batas waktu dan percobaan terbatas mencegah retry menahan resource tanpa batas. Panduan engineering AWS menjelaskan kenapa retry bisa memperkuat overload dan kenapa batas waktu tidak membuktikan suatu operasi tidak berdampak. Panduan AWS tentang batas waktu dan retry

Jangan replay stream atau aksi agen secara membabi buta

Stream yang berhenti setelah menampilkan teks tidak sama dengan permintaan yang ditolak sebelum pekerjaan dimulai. Antarmuka kamu perlu status belum selesai yang eksplisit. Memulai ulang secara otomatis bisa menduplikasi teks, memakai token tambahan, atau menghasilkan jawaban berbeda.

Alur kerja agen perlu batas tambahan: retry generasi model tidak boleh otomatis replay aksi tool yang sudah selesai. Catat hasil aksi dan gunakan mekanisme idempotensi di mana layanan aksi mendukungnya. Respons yang gagal bukan alasan untuk mengirim email yang sama atau membuat pesanan yang sama dua kali.

Pantau pekerjaan logis, bukan hanya keberhasilan HTTP

Lacak ini secara terpisah:

• Operasi logis dan percobaan upstream.
• Waktu tunggu antrean dan permintaan yang sedang berjalan.
• Penolakan berdasarkan alasan error yang didokumentasikan.
• Pemakaian input/output dan biaya per operasi yang selesai.
• Batas waktu, pekerjaan yang dibatalkan, dan stream yang belum selesai.

Gunakan pengenal permintaan dan metadata yang sudah dibersihkan. Hindari mencatat header otorisasi atau prompt lengkap secara default. Tingkat error yang menurun bukan berarti menang kalau percobaan ulang menggandakan biaya setiap tugas yang selesai.

Periksa kontrol gateway secara terpisah dari kapasitas

Informasi harga dan akun yang dipublikasikan cheapaimodel menjelaskan anggaran per key, kedaluwarsa, daftar yang diizinkan untuk model/IP, dan respons 403 saat saldo akun habis. Kondisi saldo itu bukan sesuatu yang bisa diselesaikan dengan backoff singkat. Kontrol tersebut juga tidak menjamin throughput permintaan atau token tanpa batas.

Sebelum melakukan scaling pada integrasi, cek dokumentasi cheapaimodel yang terbaru dan pastikan batas yang berlaku untuk route yang ingin kamu gunakan. Buat kontrol penerimaan dan kebijakan percobaan ulang tetap bisa dikonfigurasi supaya perubahan tidak perlu menulis ulang logika aplikasi.

Tujuannya adalah pekerjaan selesai yang bisa diprediksi: waktu tunggu yang terbatas, kegagalan yang bisa dijelaskan, pengeluaran yang terkendali, dan percobaan ulang yang membantu pemulihan, bukan melawannya.