Batas & Kuota

Batas yang berlaku di workspace Anda, dan apa yang terjadi saat tercapai.

Melihat pemakaian Anda

Menu Pengaturan menampilkan batas workspace Anda saat ini beserta riwayat pemakaian per bulan.

Menu Ringkasan menampilkan pemakaian bulan berjalan dengan indikator kuota.

Lewat API:

curl -H "X-Api-Key: $KEY" https://wa.vexahostcloud.my.id/api/v1/health

{
  "success": true,
  "data": {
    "sessions": { "total": 2, "connected": 1, "limit": 3 },
    "usage": {
      "period": "2026-08",
      "messages_sent": 143,
      "messages_received": 27,
      "messages_failed": 2,
      "quota": 1000
    }
  }
}

Jenis batas

Jumlah nomor

Berapa banyak nomor WhatsApp yang bisa ditautkan sekaligus, tergantung paket Anda.

Saat tercapai, membuat sesi baru ditolak:

{ "success": false, "error": { "message": "Tenant sudah memakai seluruh jatah sesi (1)." } }

Hapus sesi yang tidak dipakai, atau naikkan paket.

Saldo (pay as you go)

Kalau workspace Anda memakai pay as you go, yang membatasi pengiriman bukan kuota bulanan melainkan saldo — dan tidak ada tanggal berakhir sama sekali.

Saat saldo tidak cukup, pengiriman ditolak:

{ "success": false, "error": { "message": "Saldo tidak cukup untuk mengirim pesan. Isi saldo dari menu Saldo di dashboard." } }

Yang perlu diingat saat menangani ini di aplikasi Anda:

• Saldo dipotong saat pesan terkirim, bukan saat diantrekan. Pesan yang gagal tidak memotong apa pun.
• Pengiriman massal memeriksa saldo dua kali — saat mengantre dan tepat sebelum kirim — jadi sebagian pesan bisa terkirim sementara sisanya gagal kalau saldo habis di tengah jalan. Periksa status tiap pesan, jangan menganggap seluruh batch berhasil.
• Kami mengabari Anda lewat WhatsApp saat saldo menipis, sebelum berhenti terjadi.

Rincian tarif, sisa pesan, dan riwayat mutasi ada di menu Saldo. Lihat Langganan & Tagihan.

Kuota pesan bulanan

Jumlah pesan keluar per bulan kalender. Pesan masuk tidak dihitung.

Kuota dihitung saat pesan diantrekan, bukan saat terkirim. Jadi pengiriman massal 1000 nomor langsung memotong 1000 dari kuota Anda, meski pengirimannya baru selesai sejam kemudian.

Alasannya: kalau dihitung belakangan, Anda bisa terlanjur mengantrekan puluhan ribu pesan sebelum ketahuan melewati batas.

Saat habis:

{ "success": false, "error": { "message": "Kuota pesan bulan ini sudah habis (1000 pesan)." } }

Kuota disetel ulang otomatis di awal bulan.

Pesan gagal tetap terhitung. Kami sudah melakukan usaha pengirimannya. Kalau angka kegagalan Anda tinggi, periksa daftar nomor tujuan — nomor yang tidak terdaftar di WhatsApp memakan kuota tanpa hasil.

Batas permintaan API

Berapa banyak permintaan HTTP per menit yang bisa dilakukan satu API key.

Melewatinya menghasilkan 429 beserta header Retry-After:

HTTP/1.1 429 Too Many Requests
Retry-After: 34

Batas ini dihitung per kunci, bukan per alamat IP — jadi beberapa aplikasi Anda di server yang sama tidak saling menghabiskan jatah.

Endpoint /api/v1/health dikecualikan, aman dipanggil sesering apa pun untuk pemantauan.

Ini berbeda dari kuota pesan. Batas permintaan mencegah lonjakan sesaat; kuota membatasi volume bulanan. Satu permintaan bulk berisi 500 nomor dihitung sebagai satu permintaan tapi 500 pesan.

Batas teknis WhatsApp

Yang berikut ini berasal dari WhatsApp, bukan dari paket Anda — berlaku sama untuk semua:

Retensi data

Riwayat pesan disimpan selama masa retensi paket Anda, lalu dipangkas otomatis. Angka pemakaian bulanan tetap tersimpan permanen.

Kalau Anda perlu menyimpan riwayat lebih lama untuk keperluan audit, salin ke sistem Anda sendiri lewat endpoint GET /api/v1/messages, atau terima setiap pesan lewat webhook.

Menangani batas di aplikasi Anda

Periksa pemakaian sebelum pengiriman besar:

$sisa = Http::withHeader('X-Api-Key', $key)
    ->get("{$base}/api/v1/health")
    ->json('data.usage');

$tersisa = $sisa['quota'] - $sisa['messages_sent'];

if (count($nomor) > $tersisa) {
    // Beri tahu tim, atau kirim sebagian dulu
}

Tangani 429 dengan menunggu, bukan mengulang segera:

if ($response->status() === 429) {
    $tunggu = (int) $response->header('Retry-After') ?: 60;
    // jadwalkan ulang setelah $tunggu detik
}

Jangan ulangi 422. Kuota habis atau nomor tidak valid tidak akan membaik dengan diulang.

Menaikkan batas

Kirim tiket dari menu Bantuan di dashboard untuk membahas paket yang sesuai dengan volume Anda — lihat Bantuan & Tiket.

Kalau kebutuhan Anda melampaui paket Elite — lebih banyak nomor, kuota lebih besar, atau retensi lebih panjang — isi formulir Enterprise di halaman harga. Batas dan harganya disusun mengikuti kebutuhan Anda.

Sebelum menaikkan, pastikan volume Anda memang wajar untuk jalur ini — baca Praktik Baik. Volume besar lewat nomor biasa punya risiko tersendiri yang tidak bisa diselesaikan hanya dengan menaikkan kuota.