API mitra (B2B)
Errors & rate limits
Partner API error codes, per-key rate limits with X-RateLimit headers, and how to retry.
On this page
Error format#
Body error berbentuk { statusCode, code, message }. message adalah teks bahasa Inggris yang mudah dibaca dan dapat berubah, jadi selalu gunakan code untuk percabangan logika.
// Success
{ "success": true, "data": ..., "total": 128, "page": 1, "limit": 20 }
// Error
{ "statusCode": 401, "code": "INVALID_API_KEY", "message": "The API key is invalid." }Catatan
Error codes#
| HTTP | code | Arti dan solusi |
|---|---|---|
| 401 | API_KEY_REQUIRED | Tidak ada kunci yang dikirim — tambahkan header X-API-Key |
| 401 | INVALID_API_KEY | Kunci tidak valid atau tidak dikenal — pastikan salinannya tidak terpotong dan bukan kunci Public API |
| 401 | KEY_REVOKED | Kunci dicabut — terbitkan kunci baru |
| 401 | KEY_EXPIRED | Kunci kedaluwarsa (termasuk kunci lama setelah masa tenggang rotasi) — gunakan kunci baru |
| 403 | PARTNER_SUSPENDED | Akun tidak aktif — hubungi esimoa |
| 403 | INSUFFICIENT_SCOPE | Permintaan di luar cakupan kunci |
| 403 | IP_NOT_ALLOWED | Dipanggil dari IP di luar daftar izin — tambahkan IP keluar server Anda |
| 404 | PRODUCT_NOT_FOUND | Produk tidak dikenal atau sudah dihentikan |
| 429 | RATE_LIMITED | Batas laju terlampaui — coba lagi setelah jumlah detik di Retry-After |
Rate limits#
Catatan
Permintaan API B2B secara default dibatasi 20,000 per jam per kunci.
Jendela 3,600 detik dimulai sejak permintaan pertama; batas per menit juga berlaku. Kuota menghitung jumlah panggilan, bukan MB yang ditransfer. Pengaturan operasional dapat mengubah kuota.
X-RateLimit-Hour-Limit · X-RateLimit-Hour-Remaining · X-RateLimit-Hour-Reset
Header ini menunjukkan batas per jam, sisa panggilan, dan waktu reset (detik Unix). Jika kuota per jam habis, akan dikembalikan HTTP 429 dan Retry-After dalam detik. Panggilan yang ditolak oleh batas per menit tidak dihitung dalam kuota per jam.
Default-nya 300 permintaan per menit per kunci (per jendela 60 detik, dibagi untuk semua server). esimoa dapat menaikkannya per akun sesuai kontrak Anda. Setiap respons terautentikasi menyertakan header kuota.
X-RateLimit-Limit— permintaan yang diizinkan per menitX-RateLimit-Remaining— sisa permintaan dalam jendela saat iniX-RateLimit-Reset— waktu jendela direset (detik Unix)Retry-After— saat 429, jumlah detik yang perlu ditunggu sebelum mencoba lagi
HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1790000000
HTTP/1.1 429 Too Many Requests
Retry-After: 18
{ "statusCode": 429, "code": "RATE_LIMITED", "message": "Rate limit exceeded (300 requests per minute)." }Retrying#
- Saat menerima 429, tunggu sesuai detik di Retry-After, lalu coba lagi.
- Coba ulang 5xx beberapa kali dengan exponential backoff.
- 400, 401, 403, dan 404 tidak akan berubah saat dicoba ulang — perbaiki penyebabnya.
- Menyimpan katalog dalam cache selama beberapa menit membuat Anda tetap jauh di bawah batas.
async function b2bFetch(url, attempt = 0) {
const res = await fetch(url, { headers: { 'X-API-Key': process.env.ESIMOA_PARTNER_KEY } });
if (res.status === 429 && attempt < 3) {
const wait = Number(res.headers.get('Retry-After') ?? 1);
await new Promise((r) => setTimeout(r, wait * 1000));
return b2bFetch(url, attempt + 1);
}
const body = await res.json();
if (!res.ok) throw Object.assign(new Error(body.message), { code: body.code, status: res.status });
return body;
}