Menangani Error

Cara membaca error dari WatZap SDK, solusi untuk error yang sering muncul, dan cara menghindari pesan terkirim dobel.

Semua error dari SDK adalah turunan WatZapError, jadi satu blok try/catch sudah cukup untuk menangani semuanya.

import { WatZap, WatZapError, ValidationError, RateLimitError } from '@watzapid/sdk'
const wz = new WatZap()
const noHp = '081234567890'

try {
  await wz.whatsapp.messages.sendText({ to: noHp, text: 'Halo' })
} catch (err) {
  if (!(err instanceof WatZapError)) throw err // error dari kode Kamu sendiri

  if (err instanceof ValidationError) {
    // Data yang dikirim salah atau kurang. Perbaiki dulu, jangan dikirim ulang apa adanya.
  } else if (err instanceof RateLimitError) {
    // Terlalu banyak request. Tunggu sesuai err.retryAfterSeconds, lalu coba lagi.
  } else if (err.mayHaveBeenProcessed) {
    // Pesan MUNGKIN sudah terkirim (misalnya koneksi putus saat menunggu jawaban).
    // Jangan langsung kirim ulang: catat dulu, lalu cek riwayat pesannya.
  }

  console.error(err.name, err.code, err.message)
}

Informasi di Setiap Error

Properti	Isi
name	Jenis error, misalnya RateLimitError
message	Pesan error dari server, atau dari SDK
code	Kode error WatZap, misalnya '1002'
httpStatus	Status HTTP dari server (kosong jika server tidak menjawab)
mayHaveBeenProcessed	true jika request mungkin sudah diproses walaupun berakhir error
retryAfterSeconds	Khusus RateLimitError: jumlah detik yang perlu ditunggu

Jenis Error dan Solusinya

Jenis error	Artinya	Yang perlu dilakukan
ValidationError	Ada data yang kurang atau salah	Perbaiki datanya, lalu kirim lagi
AuthenticationError	API Key salah	Cek API Key di member area
PermissionDeniedError	Paket habis atau belum mendukung fitur ini, atau nomor belum terhubung	Cek paket dan koneksi nomor di dashboard
NotFoundError	Data tidak ditemukan, misalnya template, list, atau Number Key salah	Cek nama atau ID yang dipakai
ConflictError	Data dengan identitas yang sama sudah ada	Gunakan ID lain
RateLimitError	Terlalu banyak request dalam waktu singkat	Tunggu sesuai retryAfterSeconds
ProviderError	Meta (WABA) atau gateway WhatsApp (Unofficial) menolak pesan	Baca isi message. Contohnya, di luar 24 jam gunakan template
InternalServerError	Gangguan di server	Coba lagi beberapa saat kemudian
APIConnectionError / APITimeoutError	Server tidak menjawab (internet putus atau terlalu lama)	Cek koneksi, dan perhatikan mayHaveBeenProcessed

SDK sudah otomatis mencoba ulang (bawaan maksimal 2 kali) untuk error sementara seperti koneksi putus, server sibuk, atau batas request per menit, selama hal itu aman dilakukan.

Pesan Mungkin Sudah Terkirim (mayHaveBeenProcessed)

Kalau koneksi putus setelah request sampai ke server, pesan bisa saja sudah terkirim ke pelanggan walaupun kode Kamu menerima error. Karena itu:

• SDK hanya mengulang kirim pesan jika pasti belum sampai ke server, sehingga retry dari SDK tidak akan membuat pesan dobel.

• Jika error punya mayHaveBeenProcessed: true, jangan langsung kirim ulang. Untuk WABA, cek dulu riwayat pesan ke nomor tersebut:

import { WatZap } from '@watzapid/sdk'
const wz = new WatZap()
const noHp = '081234567890'
const riwayat = await wz.whatsapp.messages.list({ phone: noHp, perPage: 5 })
console.log(riwayat.items.map((pesan) => `${pesan.createdAt}  ${pesan.status}`))

Jangan bungkus fungsi kirim pesan dengan loop retry buatan sendiri. SDK sudah mengulang otomatis saat aman, dan retry tambahan berisiko membuat pelanggan menerima pesan yang sama berkali-kali.

Pesan Error yang Sering Muncul

Pesan error	Penyebab	Solusi
Missing API key	SDK tidak menemukan API Key	Pastikan WATZAP_API_KEY terisi dan program dijalankan dengan --env-file=.env
Invalid Secret Key / Invalid API Key	API Key salah	Salin ulang dari member area
Need Upgrade Package	Paket belum mendukung fitur API	Upgrade paket langganan
Your package is expired	Paket sudah habis	Perpanjang paket langganan
Please Connect WhatsApp Business API First	Belum ada nomor WABA yang terhubung	Hubungkan nomor WABA
License Not Found	Number Key salah	Cek ulang Number Key
WhatsApp Instance Not Started	Nomor Unofficial sedang tidak terhubung	Reconnect nomor di dashboard
Template not found	Nama atau bahasa template tidak cocok	Samakan nama template, dan isi language bila ada beberapa bahasa
Limit Exceeded …	Lebih dari 30 pesan per menit	Kirim lebih pelan. SDK otomatis mencoba lagi setelah jeda singkat
Pesan dari Meta, misalnya (#131047) …	Meta menolak pesan, sering karena sudah di luar 24 jam	Gunakan template