Troubleshooting

Error yang paling sering ditemui, artinya, dan cara mengatasinya. Semua error WAQ berbentuk JSON dengan field error (kode mesin) dan message (penjelasan).

401 — Unauthorized

error	Penyebab	Solusi
invalid_credentials	Email/password salah saat login	Cek ulang; password case-sensitive
invalid_token	Token verifikasi email salah/kedaluwarsa (>24 jam)	Daftar ulang atau minta token baru ke admin
invalid_refresh	Refresh token tidak valid	Login ulang dari awal
Token tidak ada / tidak valid	Header Authorization: Bearer <jwt> hilang, salah format, atau JWT kedaluwarsa (umur access token 15 menit)	Refresh via POST /v1/auth/refresh, atau pakai X-API-Key untuk integrasi server (tidak kedaluwarsa)

402 — Payment Required

error	Penyebab	Solusi
subscription_inactive	Langganan expired/suspended — kirim pesan diblokir	Upgrade paket
device_limit_reached	Jumlah device sudah maksimal utk paketmu	Hapus device tak terpakai, atau upgrade
contact_limit_exceeded	Kontak sudah 10.000 (limit akun)	Hapus kontak lama

403 — Forbidden

error	Penyebab	Solusi
email_not_verified	Login sebelum email diverifikasi	Selesaikan verifikasi (lihat Quickstart langkah 2)
Bukan admin	Akses endpoint /v1/admin/* dengan akun biasa	Endpoint itu khusus admin

404 — Not Found

Resource (device/pesan/kontak/webhook) tidak ada atau bukan milikmu — WAQ tidak membedakan keduanya (keamanan). Cek ID-nya benar dan berasal dari akunmu sendiri.

409 — Conflict

error	Penyebab	Solusi
email_taken	Email sudah terdaftar	Login, atau pakai email lain
device_not_connected	Kirim pesan/broadcast lewat device yang belum connected	Scan QR dulu (GET /v1/devices/:id/qr), lalu POST .../sync sampai connected
Pengajuan pending	Ajukan upgrade saat masih ada pengajuan menunggu	Tunggu admin proses yang pertama

429 — Too Many Requests

error	Penyebab	Solusi
daily_limit_reached	Kuota pesan harian device habis (limit paket / warmup mode)	Tunggu reset tengah malam, atau upgrade paket. Nomor baru dibatasi bertahap 7 hari pertama (50 → naik 50/hari) — ini perlindungan anti-ban, bukan bug
rate_limit_exceeded	Terlalu banyak request via API key (default 60 request/menit per key)	Pelankan laju request — cek header X-RateLimit-Remaining di tiap respons untuk tahu sisa kuota menit berjalan

400 — Bad Request

Kasus	Solusi
invalid_phone	Format nomor: 62… atau 08… (dinormalisasi otomatis), 9–15 digit
schedule_in_past / schedule_too_far	schedule_at harus di masa depan, maksimal 90 hari
consent_required (import grup)	Centang persetujuan dasar sah menghubungi kontak (consent_acknowledged: true)
no_recipients (broadcast)	Semua target ter-filter (opt-out / tidak ada yang opt-in) — cek status opt-in kontakmu
Validasi field	Baca message — menyebutkan field mana yang salah

Pesan stuck di queued?

Normal untuk beberapa detik–menit: pesan dikirim lewat antrean dengan delay acak (anti-ban), bukan instan. Kalau >10 menit tetap queued:

1. Cek device masih connected (POST /v1/devices/:id/sync).
2. Cek pesan lain di antrean (banyak antrean = makin lama, pacing disengaja).
3. Kalau failed, baca error_message-nya.

QR tidak bisa discan?

QR WhatsApp kedaluwarsa ±30 detik. Panggil GET /v1/devices/:id/qr lagi untuk QR baru, scan secepatnya. Pastikan HP online dan WhatsApp versi terbaru.

Masih stuck?

Hubungi admin via kontak di halaman Billing (bagian konfirmasi pembayaran — kontak yang sama).

Kuota harian & warmup

Broadcast berhenti di tengah jalan dengan stopped_reason berisi "Limit harian … tercapai", atau pengiriman ditolak 429 daily_limit_reached.

Batas harian sebuah device = yang terkecil antara dua hal:

1. Pemanasan (warmup) — device baru dibatasi bertahap: hari 1 = 50 pesan, +50 tiap hari, penuh mulai hari ke-7. Tujuannya menghindari pemblokiran nomor oleh WhatsApp.
2. Jatah paket — lihat Billing & Paket.

Cek posisi kuota hari ini:

curl https://waq.karyawah.id/v1/devices/health -H "Authorization: Bearer $TOKEN"

{"data": [{
  "name": "CS 1", "warmup_active": true, "warmup_day": 2, "warmup_total_days": 7,
  "daily_limit": 100, "plan_limit": 1000, "sent_today": 50, "remaining_today": 50
}]}

Hitungan hari mengikuti jam server (UTC), jadi kuota berganti pukul 08.00 WITA.

Mengubah pengaturan pengiriman

Pemanasan bersifat opsional — nomor yang sudah lama dipakai berkomunikasi tidak perlu diperlakukan seperti nomor baru:

curl -X PATCH https://waq.karyawah.id/v1/devices/<device_id> \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"warmup": false, "daily_limit": 1000, "delay_min": 3, "delay_max": 10}'

Field	Arti
warmup	false = batas harian langsung berlaku penuh
daily_limit	Batas pesan/hari. Melebihi jatah paket akan diturunkan otomatis dan ditandai daily_limit_capped
delay_min / delay_max	Jeda acak antar pesan (detik). Makin rapat makin cepat, makin mudah terdeteksi sebagai robot

Mematikan pemanasan pada nomor baru berisiko

Nomor yang baru terhubung lalu langsung mengirim ratusan pesan ke orang yang belum pernah berinteraksi adalah pola yang paling sering diblokir WhatsApp. Validasi dulu nomor tujuan (lihat Kontak & Opt-in) dan naikkan batas bertahap.

Broadcast terkirim ke 0 nomor?

Cek dengan pratinjau. Kalau total: 0 padahal kontak banyak, penyebab tersering: kontak belum ditandai opt-in. Broadcast segmen secara bawaan hanya menyasar kontak yang sudah memberi persetujuan — lihat Kontak & Opt-in.