Rate Limit & Kuota

Gateway membatasi kecepatan pengiriman untuk menjaga kesehatan nomor WhatsApp Anda dan mencegah penyalahgunaan.

---

Endpoint mana yang dibatasi?

Semua pembatasan di halaman ini berlaku untuk setiap endpoint yang benar-benar mengirim pesan, bukan hanya POST /v1/messages:

Endpoint	Rate limit & cooldown	Menghitung kuota
POST /v1/messages	Ya	Ya
POST /v1/sessions/{id}/newsletters/{nl}/messages	Ya	Ya
Kirim uji cepat di Dashboard	Ya (lebih ketat)	Ya

Nomor yang sama berbagi satu jatah: mengirim lewat channel atau lewat tombol kirim uji di Dashboard ikut menghabiskan rate limit, cooldown, dan kuota nomor tersebut.

---

Empat Jenis Pembatasan

1. Rate Limit Per Tier (Kecepatan Pengiriman)

Membatasi berapa banyak pesan yang bisa Anda kirim per menit dari satu nomor, tergantung paket langganan.

Paket	Rate Limit	Burst (1 menit pertama)	Keterangan
Free	10 pesan/menit	10	Hanya teks, 1 nomor
Pro	20 pesan/menit	20	Teks + attachment, unlimited nomor
Max	30 pesan/menit	30	Semua format + grup + channel, unlimited nomor
WagWay Partner	Custom	Custom	Sesuai kesepakatan

Burst artinya boleh kirim hingga limit tersebut dalam 1 menit pertama, lalu di-pace di kemudian hari. Contoh: paket Pro boleh kirim 20 pesan sekaligus, tapi jika terus-menerus kirim 20/menit, akan dibatasi ke ~0.33 pesan/detik.

Per akun (lintas semua nomor): maksimal 20 pesan/detik dengan burst hingga 40. Ini adalah batas atas — rate limit per nomor itu yang lebih ketat menjadi pembatas sesungguhnya.

2. Cooldown Pesan Beruntun (Platform Hygiene)

Setelah mengirim 100 pesan berturut-turut dari satu nomor tanpa jeda, sistem otomatis mem-pause pengiriman dari nomor itu selama 5 menit.

"Berturut-turut" = tanpa jeda ≥ 60 detik antar pesan. Jika Anda berhenti 60+ detik, hitungan reset ke nol.

Tujuan: higiene nomor. Pola "senapan mesin" (ratusan pesan tanpa henti) adalah sinyal spam yang mudah dibaca Meta.

3. Batas Aksi Paralel Per Nomor

Maksimal 5 request paralel ke WhatsApp dari satu nomor untuk operasi sinkron (cek grup, ubah profil, validasi kontak, dll). Request ke-6 ditolak sambil menunggu yang lain selesai.

Tujuan: menjaga kesehatan koneksi sesi. Banyak request paralel ke WhatsApp = beban, risiko disconnect.

4. Kuota Periode Langganan

Membatasi berapa total pesan yang bisa dikirim dalam satu periode langganan.

• Batas kuota tergantung paket langganan Anda
• Periode dihitung rolling dari tanggal aktivasi paket, bukan kalender bulan
• Sisa kuota bisa dilihat di Dashboard → Penggunaan

Kuota hanya dipantau lewat portal

Belum ada endpoint API untuk mengecek sisa kuota/pemakaian secara programatik — pantau lewat Dashboard → Penggunaan. Secara program, Anda hanya tahu kuota habis saat menerima 429 dengan body {"error":"message quota exhausted"}.

---

Apa yang Terjadi Saat Limit Terlampaui?

Server merespons dengan 429 Too Many Requests. Bedakan berdasarkan pesan error:

Rate Limit Per Nomor

{
  "error": "session send rate exceeded"
}

Header: Retry-After: N (tunggu N detik).

Rate Limit Per Akun

{
  "error": "user rate limit exceeded"
}

Header: Retry-After: N.

Cooldown Pesan Beruntun

{
  "error": "consecutive send cooldown: too many messages sent back-to-back on this number; pause before sending again"
}

Header: Retry-After: N (standar 300 detik = 5 menit). Pesan error berbeda dari rate limit supaya Anda tahu ini adalah hygiene pause, bukan teknis congestion.

Batas Aksi Paralel

{
  "error": "too many concurrent requests for this number; retry shortly"
}

Header: Retry-After: 1. Terjadi saat mencoba operasi grup/profil/kontak saat sudah ada 5 request lain berlangsung untuk nomor itu.

Kuota Habis

{
  "error": "message quota exhausted"
}

Tidak ada header Retry-After — kuota pulih di perpanjangan periode langganan.

---

Cara Menangani Rate Limit

Cara 1 — Antrekan Pesan (Direkomendasikan)

Alih-alih mengirim langsung dari loop, masukkan pesan ke antrean internal aplikasi Anda, lalu proses dengan kecepatan yang terkontrol. Sesuaikan delay dengan paket Anda:

// Contoh: paket Pro (20 pesan/menit = 3 detik per pesan)
async function kirimDenganDelay(pesanList) {
  const delayMs = 3000 // 3 detik untuk Pro; gunakan 6 detik untuk Free, 2 detik untuk Max
  for (const pesan of pesanList) {
    await kirimPesan(pesan)
    await tunggu(delayMs)
  }
}

Cara 2 — Exponential Backoff saat 429

Jika mendapat 429, tunggu sebelum retry. Setiap gagal, gandakan waktu tunggu:

async function kirimDenganRetry(payload, maxCoba = 5) {
  let tungguMs = 1000 // mulai 1 detik

  for (let coba = 1; coba <= maxCoba; coba++) {
    const resp = await fetch('/v1/messages', {
      method: 'POST',
      body: JSON.stringify(payload),
      headers: { /* ... */ }
    })

    if (resp.status === 429) {
      const retryAfter = resp.headers.get('Retry-After') || 1
      await new Promise(r => setTimeout(r, retryAfter * 1000))
      tungguMs = Math.min(tungguMs * 2, 30000) // maks 30 detik
      continue
    }

    return resp.json()
  }

  throw new Error('Gagal setelah beberapa kali retry')
}

---

Tips Menjaga Nomor WhatsApp Tetap Sehat

Selain batas teknis, ada batas "etika" penggunaan WhatsApp yang penting dijaga:

• Kirim ke penerima yang relevan. Mengirim pesan ke banyak orang yang tidak mengenal Anda berisiko nomor dilaporkan sebagai spam dan diblokir oleh WhatsApp.
• Hindari pengiriman massal ke nomor acak. WhatsApp aktif mendeteksi pola spam.
• Jaga rasio balasan. Nomor yang banyak kirim tapi tidak pernah dibalas dicurigai sebagai spam.
• Gunakan untuk komunikasi yang diharapkan pengguna — notifikasi transaksi, OTP, update pesanan, dll.

---

Pantau Penggunaan

Dari Dashboard → Penggunaan, Anda bisa melihat:

• Total pesan terkirim hari ini dan pada periode langganan berjalan
• Sisa kuota periode berjalan
• Grafik penggunaan 14 hari terakhir