Rate Limits

API Volara membatasi laju permintaan per API key untuk menjaga stabilitas dan mencegah penyalahgunaan. Saat batas terlampaui, API mengembalikan status 429.

Header kuota

Setiap respons menyertakan header yang menggambarkan kuota saat ini:

Header	Arti
RateLimit-Limit	Jumlah maksimum permintaan dalam jendela waktu.
RateLimit-Remaining	Sisa permintaan pada jendela saat ini.
RateLimit-Reset	Detik tersisa (atau timestamp) sampai kuota di-reset.
Retry-After	(Pada 429) berapa detik harus menunggu sebelum mencoba lagi.

Nama header bisa bervariasi

Selalu baca nilai dari respons, jangan hard-code angka kuota. Untuk batas pasti per-endpoint, lihat Referensi API interaktif.

Menangani 429

Saat menerima 429 Too Many Requests, jangan langsung mengulang. Tunggu sesuai Retry-After (atau RateLimit-Reset), lalu retry dengan exponential backoff dan jitter.

async function requestWithRetry(url: string, init: RequestInit, max = 5) {
  for (let attempt = 0; attempt < max; attempt++) {
    const res = await fetch(url, init)
    if (res.status !== 429) return res

    const retryAfter = Number(res.headers.get('Retry-After')) || 2 ** attempt
    const jitter = Math.random() * 0.3 * retryAfter
    await new Promise((r) => setTimeout(r, (retryAfter + jitter) * 1000))
  }
  throw new Error('Rate limit: gagal setelah beberapa percobaan')
}

Praktik baik

• Pakai webhooks, bukan polling, untuk event masuk — lihat Webhooks.
• Batch dan beri jeda pekerjaan besar (mis. impor kontak, broadcast).
• Hormati RateLimit-Remaining dan perlambat sebelum mencapai nol.
• Idempotency pada write agar retry aman (kirim ulang idempotency-key yang sama).

Langkah selanjutnya

• Errors untuk amplop error dan kode lain.
• Pagination untuk mengambil data besar tanpa membebani API.