Batas Penggunaan

Halaman ini menyebut angka yang benar-benar dipasang di kode produksi, bukan angka rencana.

#Ringkasan

Tiga berkas endpoint memeriksa API key hari ini: /api/products.php, /api/customer_lookup.php, dan /api/order_status.php. Aturan batas lajunya berbeda, dan perbedaannya bukan detail kecil — yang pertama dihitung per alamat IP, yang kedua per API key.

/api/products.php: tidak ada kuota per key, tidak ada kuota harian, tidak ada kuota bulanan. /api/customer_lookup.php: ada kuota per key, dan ada kuota harian. Tidak ada header sisa kuota di kedua endpoint. Rinciannya di bawah.

#/api/products.php — cara hitungnya

Server menyimpan daftar waktu request per alamat IP untuk endpoint tersebut, dan memakai jendela geser 60 detik:

1. Setiap request masuk, waktu-waktu yang lebih tua dari 60 detik dibuang dari daftar.
2. Waktu request saat ini ditambahkan.
3. Kalau jumlah request dalam daftar melebihi 60, IP tersebut diblokir.

Artinya request ke-61 dalam rentang 60 detik adalah yang memicu blokir. Request ke-1 sampai ke-60 dilayani.

Begitu terpicu, IP diblokir selama 60 detik penuh terhitung dari saat pemblokiran, bukan sampai jendela lama habis. Selama diblokir, semua request dari IP itu ke endpoint tersebut langsung dibalas 429 tanpa diproses.

#Dihitung per IP, bukan per key

Ini yang paling sering salah diasumsikan orang. Hitungannya melekat pada alamat IP pemanggil, bukan pada API key.

Konsekuensi praktisnya:

• Dua API key berbeda yang dipanggil dari satu server berbagi jatah yang sama.
• Semua trafik ke /api/products.php dari IP itu ikut dihitung, termasuk request yang gagal.
• Kalau integrasi Anda berjalan di beberapa server dengan IP berbeda, tiap server punya jatahnya sendiri.
• Kalau integrasi Anda berjalan di belakang satu NAT atau satu IP keluar bersama, semua proses di belakangnya berbagi satu jatah.

Pemeriksaan batas laju berjalan sebelum pemeriksaan API key. Request tanpa key, dengan key salah bentuk, atau dengan key yang sudah dicabut tetap memakan jatah. Mengulang-ulang request yang gagal 401 adalah cara tercepat mengunci IP Anda sendiri.

#/api/customer_lookup.php — dihitung per key

Endpoint Pencarian Pelanggan memakai aturan yang berbeda. Kontrol utamanya melekat pada API key, bukan pada alamat IP.

Konsekuensi praktisnya, dan ini kebalikan dari /api/products.php:

• Menyebar panggilan ke banyak server tidak menambah jatah. Satu key tetap satu jatah, dari IP mana pun.
• Ketiga jendela per-key berlaku bersamaan. Yang pertama tersentuh yang menolak. Rata-rata aman jangka panjang adalah 4.000 per hari, bukan 30 per menit dikalikan 1.440.
• Batas 120 per 60 detik melekat pada pasangan key + IP, bukan pada IP saja. Dua tenant yang memanggil dari satu IP keluar yang sama punya jatah 120 masing-masing; satu tenant yang berisik tidak bisa mengunci tenant lain di IP itu.
• Satu-satunya jatah yang benar-benar dipakai bersama adalah 1.200 per 60 detik per IP. Ia berjalan sebelum key dibaca, jadi ia tidak bisa dibedakan per key. Tugasnya melindungi server dari banjir, bukan membatasi tenant: 1.200 per menit setara 40 key yang semuanya sedang di puncak jatah sahnya.
• Ada satu rem tambahan berbasis database, 45 per 60 detik, yang menangkap ledakan permintaan paralel yang lolos dari penghitung berbasis berkas. Klien yang memanggil berurutan tidak akan pernah menyentuhnya.

Dua hal lain yang khusus di endpoint ini:

• Waktu jawab minimum 150 milidetik, disengaja dan sama untuk pencarian yang menemukan maupun yang tidak. Jangan memasang timeout klien di bawah 2 detik.
• Setiap pencarian dicatat, termasuk yang tidak menemukan apa pun, dengan nomor tersamar. Pola pemanggilan yang menyerupai penyisiran daftar nomor akan ditandai untuk ditinjau manual, dan kunci yang mencurigakan bisa dicabut pemilik akun.

#Yang dikembalikan saat terlampaui

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json; charset=utf-8

{"error":"Terlalu banyak permintaan. Coba lagi nanti."}

• Retry-After berisi jumlah detik, bukan tanggal HTTP. Selalu ikut pada 429.
• Pada request yang memicu blokir, nilainya sama dengan lebar jendela yang tersentuh: 60, 3600, atau 86400.
• Pada request berikutnya selama masih diblokir, nilainya adalah sisa detik blokir — jadi nilainya mengecil kalau Anda terus mencoba.

Hormati Retry-After. Mencoba lagi lebih cepat tidak memperpanjang blokir, tetapi juga tidak membantu apa pun.

#Header sisa kuota: tidak ada

Response AdForm tidak memuat header berikut, baik saat sukses maupun saat gagal:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset
• RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (bentuk standar IETF)

Kalau kode Anda membaca salah satu header itu, hasilnya akan selalu kosong. Satu-satunya sinyal batas laju yang dikirim server adalah Retry-After, dan itu hanya muncul bersama 429.

Konsekuensinya: Anda tidak bisa tahu sisa jatah sebelum kena. Hitung sendiri di sisi Anda kalau perlu, atau — lebih sederhana dan lebih tahan banting — batasi laju kirim Anda sendiri di bawah ambang.

#Yang kami sarankan

• Batasi diri ke sekitar 1 request per detik. Itu jauh di bawah 60 per menit dan memberi ruang untuk trafik lain dari IP yang sama.
• Jangan menjalankan banyak proses paralel dari satu IP untuk memanggil endpoint yang sama. Serialkan, atau pakai antrean dengan satu pekerja.
• Ulangi hanya 429 dan 5xx. 401, 403, 400, dan 404 adalah kesalahan tetap; mengulanginya membuang jatah.
• Pakai jeda yang membesar untuk percobaan ulang, dimulai dari nilai Retry-After.
• Untuk pekerjaan massal (misalnya menduplikasi puluhan produk), jalankan berurutan dengan jeda, dan simpan kemajuannya supaya bisa dilanjutkan tanpa mengulang dari awal — operasi tulis tidak idempoten, lihat Konvensi API.

#Sifat pembatas ini

Dua catatan jujur supaya Anda tidak salah menganggapnya sebagai jaminan:

• Penghitungnya disimpan di sisi server dan bersifat best-effort. Ia bukan janji kontraktual, melainkan rem pengaman. Angka dan perilakunya bisa diperketat kalau ada penyalahgunaan.
• Perubahan yang memperketat batas termasuk perubahan yang merusak, dan akan diumumkan lebih dulu sesuai kebijakan perubahan kontrak.

#Batas lain yang bisa Anda temui

Dua batas berikut bukan batas API, tetapi memengaruhi hasil kalau integrasi Anda menyangkut form order yang dipasang di situs pelanggan.

#Pembatasan anti-spam pada form order

Pengiriman pesanan dari form order dibatasi per alamat IP sebagai perlindungan anti-spam. Kalau Anda menguji dengan mengirim banyak pesanan berturut-turut dari satu komputer, pengiriman akan ditolak sementara. Ini perilaku yang diharapkan, bukan gangguan. Beri jeda antar-pengujian, atau uji dengan produk khusus uji coba.

#Kuota pesanan paket gratis

Tenant pada paket gratis punya batas jumlah pesanan yang bisa masuk lewat form:

Setelah batas tercapai, form berhenti menerima pesanan dan menampilkan pesan kepada pembeli — Promo hari ini telah berakhir, coba lagi besok ya. untuk batas harian, dan Kuota pesanan gratis bulan ini sudah penuh. Sampai jumpa bulan depan ya. untuk batas bulanan. Pengiriman ditolak dengan status 429.

Tenant pada paket berbayar tidak dibatasi seperti ini.

Kalau form yang Anda pasang tiba-tiba menolak pesanan padahal pemasangannya benar, periksa dulu status paket tenant sebelum mencari bug di kode Anda.

#Butuh throughput lebih tinggi?

Hubungi kami lewat Pusat Bantuan sebelum menaikkan beban. Sertakan: perkiraan request per menit dan per hari, pola trafiknya (merata atau menumpuk), alamat IP keluar yang Anda pakai, dan apa yang integrasi Anda kerjakan. Lebih mudah bagi kami menyiapkan kapasitas daripada menelusuri lonjakan yang tidak diberitahukan.