Memahami Rate Limit dan Penanganan Error di API Kencang.in

Integrasi yang baik bukan hanya berjalan saat semuanya lancar, tetapi juga tahu harus berbuat apa saat server menolak permintaan. Artikel ini membahas dua hal yang paling sering menyebabkan integrasi API Kencang.in bermasalah: melebihi rate limit dan salah menafsirkan error.

Bagaimana rate limit bekerja

Rate limit membatasi jumlah permintaan per menit per kunci API. Tujuannya menjaga stabilitas layanan untuk semua pengguna. Batasnya bergantung pada paket: Pro mendapat 60 permintaan per menit, Bisnis 300 per menit; rinciannya ada di halaman harga. Hitungan direset setiap menit (jendela tetap), bukan jendela bergeser.

Setiap respons menyertakan header:

• X-RateLimit-Limit: batas per menit untuk kunci Anda.
• X-RateLimit-Remaining: sisa permintaan pada menit berjalan.
• Retry-After: hanya pada respons 429, jumlah detik sebelum Anda boleh mencoba lagi. Header ini distandarkan di MDN.

Strategi agar tidak terkena 429

1. Batching di sisi Anda. Jika perlu membuat 500 link, jangan tembak sekaligus. Antrekan dan proses sesuai batas, misalnya 50 per menit dengan jeda merata.
2. Cache hasil. Data yang jarang berubah, seperti daftar domain atau detail link, tidak perlu diminta berulang.
3. Pakai endpoint daftar dengan paginasi alih-alih memanggil detail satu per satu.
4. Pantau X-RateLimit-Remaining dan perlambat secara proaktif saat mendekati nol.

Menangani 429 dengan exponential backoff

Saat menerima 429, hormati Retry-After. Jika header tidak ada, gunakan exponential backoff: tunggu 1, 2, 4, 8 detik, ditambah jitter acak agar banyak klien tidak mencoba ulang pada detik yang sama. Pola ini direkomendasikan luas, termasuk dalam panduan retry Google Cloud.

Kode error dan artinya

• 400 Bad Request: body bukan JSON yang valid atau parameter wajib hilang. Periksa Content-Type dan struktur payload.
• 401 Unauthorized: kunci API hilang, salah, atau sudah dicabut. Jangan retry; perbaiki kunci.
• 403 Forbidden: fitur tidak termasuk paket Anda, misalnya domain bermerek pada paket Gratis, atau kuota link bulanan habis.
• 404 Not Found: ID link tidak ada atau bukan milik akun Anda.
• 429 Too Many Requests: rate limit. Tunggu dan ulangi.
• 500/502/503: gangguan sementara di sisi server. Retry dengan backoff, maksimal beberapa kali, lalu catat untuk ditinjau.

Selain status HTTP, body respons selalu memuat error dan message. Kesalahan validasi bisnis, seperti "alias sudah digunakan" atau "URL diblokir karena berbahaya", dikembalikan dengan status 200 dan error: 1. Jadi periksa keduanya. Pemeriksaan keamanan URL dijelaskan di artikel keamanan link pendek.

Idempotensi dan duplikasi

Jika permintaan POST timeout di jaringan, Anda tidak tahu apakah link sudah dibuat. Mengulanginya bisa menghasilkan dua link. Solusinya: pakai alias deterministik (misalnya ID pesanan). Jika alias sudah ada, API mengembalikan error "alias sudah digunakan", dan aplikasi Anda bisa mengambil link yang ada lewat endpoint pencarian alih-alih membuat baru.

Logging yang berguna

Catat untuk setiap pemanggilan: endpoint, status HTTP, nilai X-RateLimit-Remaining, dan message saat gagal. Jangan mencatat kunci API. Dengan log ini, Anda bisa melihat pola, misalnya lonjakan 429 setiap jam 9 pagi saat cron berjalan, lalu menyebar jadwalnya.

Kapan sebaiknya naik paket

Jika log menunjukkan Anda rutin menyentuh batas meski sudah batching, itu tanda beban nyata, bukan bug. Paket Bisnis memberi 300 permintaan per menit dan link tanpa batas. Untuk kebutuhan di atas itu, hubungi kami untuk paket kustom. Contoh kode dasar untuk ketiga bahasa ada di artikel contoh kode API, dan dokumentasi lengkap di halaman developer.

Pertanyaan umum

Apakah rate limit dihitung per akun atau per kunci?

Per kunci API. Jika Anda memakai beberapa integrasi, buat kunci terpisah untuk masing-masing agar satu integrasi yang sibuk tidak menghabiskan kuota integrasi lain, dan agar pemantauan penggunaan lebih mudah dibaca di dasbor.

Apakah permintaan yang ditolak dengan 429 ikut dihitung?

Tidak. Permintaan yang ditolak karena melebihi batas tidak mengurangi kuota menit berikutnya. Namun mengirim permintaan terus-menerus saat sudah dibatasi membuang sumber daya, jadi hormati header Retry-After.

Bagaimana menaikkan batas permintaan?

Naik ke paket Bisnis untuk mendapatkan 300 permintaan per menit. Untuk kebutuhan di atas itu, misalnya integrasi dengan jutaan link, hubungi kami untuk paket kustom dengan batas yang disesuaikan.

Apakah error 5xx berarti link saya hilang?

Tidak. Error 5xx menandakan gangguan sementara saat memproses permintaan, bukan kehilangan data. Coba ulang dengan backoff; jika gangguan berlanjut lebih dari beberapa menit, periksa halaman status atau hubungi kami.