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).