# 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:

```bash
curl -H "X-Api-Key: $KEY" https://pesanvo.com/api/v1/health
```

```json
{
  "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:

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

Hapus sesi yang tidak dipakai, atau naikkan paket.

### Kuota pesan bulanan

Jumlah pesan **otomatis** keluar per bulan kalender: pesan lewat API, kampanye, dan pengingat tagihan. Balasan manual dari Inbox dan 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:

```json
{ "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:

| Batas | Nilai |
|---|---|
| Panjang pesan teks | 4096 karakter |
| Ukuran lampiran | 16 MB |
| Panjang caption media | 1024 karakter |
| Nomor per permintaan massal | 1000 (batas kami, demi kestabilan) |

## 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](WEBHOOK.md).

## Menangani batas di aplikasi Anda

**Periksa pemakaian sebelum pengiriman besar:**

```php
$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:**

```php
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](BANTUAN.md).

Kalau kebutuhan Anda melampaui paket Scale — 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](PRAKTIK_BAIK.md). Volume besar lewat nomor biasa punya risiko tersendiri yang tidak bisa diselesaikan hanya dengan menaikkan kuota.