Referensi
Rate limit
Batas melindungi API dari banjir permintaan, bukan dari reseller biasa. Setiap akun memiliki satu batas per menit yang naik seiring pengeluarannya, dan beberapa batas sempit mencakup aksi yang berat. Aturan yang terkait satu order, seperti jeda isi ulang, mengembalikan kode error sendiri, bukan 429.
Lapisan rate limit
Per-IP
20.000 request / menit / alamat IP
Diterapkan sebelum validasi key sehingga enumerasi key secara brute-force terbatas. Dibagi di antara semua key di balik IP yang sama. Default diatur secara global dan tidak dapat dikonfigurasi pengguna.
Window akun bersama
120–2.400 request / 60 detik bergulir
Semua API key aktif dalam satu akun memakai counter yang sama. Ladder lifetime successful spend memasok batas kecuali ada override RPM langsung.
Khusus action
Bergantung pada action
Services, catalog, cancel, refill, dan aksi webhook memiliki batas sempit sendiri, ditampilkan di bawah. Batas ini ditambahkan ke batas akun; tidak menggantikannya.
Batas per aksi
Batas ini dihitung per akun per menit. 429 dari salah satunya melaporkan action di X-RateLimit-DeniedBy. Cancel dan refill menghitung ID order, bukan permintaan, sehingga satu panggilan untuk 10 order memakai 10 dari ID yang Anda miliki per menit. Cancel atau refill dengan ID lebih banyak dari itu, hingga 100, diterima jika merupakan panggilan pertama Anda di menit tersebut dan memakai seluruh menit itu.
| Aksi | Per menit | Yang dihitung |
|---|---|---|
| services | 10 | Permintaan |
| catalog | 30 | Permintaan |
| cancel | 30 | ID order |
| refill | 30 | ID order |
| webhook.* | 10 | Permintaan |
Ladder lifetime successful spend
Batas akun Anda mengikuti pengeluaran berhasil seumur hidup Anda; tingkat yang lebih tinggi langsung membuka batas yang lebih tinggi. Batas atas IP sebesar 20.000 permintaan per menit berlaku sebelum kunci diperiksa. Admin dapat menetapkan batas langsung untuk akun, hingga 10.000. Tingkat akun Anda ada di header X-RateLimit-Tier dan di halaman API Anda.
| Tier | Minimum lifetime spend | Request / menit |
|---|---|---|
| 0 | $0 | 120 |
| 1 | $10 | 300 |
| 2 | $50 | 600 |
| 3 | $100 | 900 |
| 4 | $500 | 1.200 |
| 5 | $1.000 | 1.800 |
| 6 | $2.500 | 2.400 |
Header response
Header response
X-RateLimit-Limit- Pada response normal, batas efektif request per menit yang dibagi oleh akun. Pada 429, batas yang dilaporkan lapisan penolak.
X-RateLimit-Remaining- Pada response normal, request tersisa di window akun bersama. Pada 429, nilai tersisa yang dilaporkan lapisan penolak.
X-RateLimit-Reset- Jumlah detik relatif hingga window dilaporkan reset; bukan timestamp Unix.
X-RateLimit-Tier- Tier yang diperoleh dari lifetime successful spend (0–6). Override RPM khusus tidak mengubah nilai ini.
X-RateLimit-DeniedBy- Dikirim pada response 429 saat limiter bernama menolak panggilan: "ip", "api_requests_per_minute", atau "action".
Retry-After- Pada 429 atau 503 yang dapat di-retry, tunggu setidaknya jumlah detik dari Retry-After sebelum mencoba lagi. Untuk action=add, gunakan kembali kunci idempotensi yang sama setelah menunggu.
Menangani respons 429
Tunggu Retry-After bila ada.
Bila tidak, tunggu sesuai detik X-RateLimit-Reset. Kedua nilai adalah jeda relatif, bukan waktu jam; tambahkan jitter sebelum mencoba lagi.Baca X-RateLimit-DeniedBy.
Header ini menyebutkan batas yang menolak panggilan. Mengganti kunci tidak membantu, karena batas akun, IP, dan aksi bersifat bersama.Gunakan webhook, bukan polling.
Webhook tiba minimal satu kali, jadi buat handler Anda idempoten dan gunakanaction=statusuntuk memeriksa hal penting.Gabungkan bila bisa.
Status, cancel, dan refill menerima hingga 100 ID dalam satu permintaan; hitungan ID order tetap berlaku untuk cancel dan refill.