Error Codes & Troubleshooting

Daftar lengkap error codes, penyebab, dan cara ngatasinnya.

DisconnectReason — Status Code

Semua error koneksi dibungkus pake Boom dari @hapi/boom. Cek statusCode lewat error.output.statusCode.

Code	Konstanta	Penyebab	Solusi
401	`DisconnectReason.loggedOut`	Session expired, logout manual, atau akun login di device lain.	Hapus folder auth, pairing ulang dari awal. Jangan reconnect otomatis.
403	`DisconnectReason.forbidden`	Akun diblokir atau terkena ban sementara oleh WhatsApp.	Cek WhatsApp Web. Kalo diblokir, ga bisa diapa-apain. Kalo banned sementara, tunggu.
408	`DisconnectReason.timedOut`	Koneksi timeout — server ga respond dalam waktu yang ditentukan.	Reconnect otomatis. Cek kestabilan internet.
408	`DisconnectReason.connectionLost`	Keep-alive gagal — server ga ngirim balasan dalam interval tertentu.	Reconnect otomatis. Cek jaringan.
428	`DisconnectReason.connectionClosed`	Koneksi ditutup server atau WebSocket error.	Reconnect otomatis. Kalo sering terjadi, cek proxy/stabilitas jaringan.
440	`DisconnectReason.connectionReplaced`	Device lain (QR / pairing code) connect pake akun yang sama.	Kalo lu sengaja, abaikan. Kalo ga sengaja, ganti password WA.
500	`DisconnectReason.badSession`	Session corrupt — key Signal atau data auth rusak.	Hapus folder auth, pairing ulang. Session ga bisa dipulihin.
503	`DisconnectReason.unavailableService`	Server WhatsApp sibuk / lagi maintenance.	Reconnect dengan delay lebih lama (5-10 detik). Jangan spam reconnect.
515	`DisconnectReason.restartRequired`	Server minta restart koneksi. NORMAL terjadi pas pertama kali pairing berhasil.	Reconnect otomatis. Ini bagian dari flow pairing — jangan panik.
411	`DisconnectReason.multideviceMismatch`	Akun belum join Multi-Device beta.	Buka WhatsApp → Linked Devices → Multi-Device beta → Gabung.

Stream Errors

Error yang dikirim server lewat <stream:error>. Biasanya muncul sebelum disconnect.

Kode	Pesan	Penyebab & Solusi
401	not-authorized	Session ga valid. Hapus auth & pairing ulang.
403	forbidden	Akun dibatasi. Cek WhatsApp Web.
404	item-not-found	Resource ga ditemukan (biasanya internal).
405	not-allowed	Aksi ga diizinkan — misal kirim pesan ke nomor yang ga diizinkan.
409	conflict	Konflik session — device lain connect.
500	internal-server-error	Error internal server WA. Coba reconnect.

Media Upload / Download Errors

Kode	Penyebab	Solusi
Media retry SUCCESS (200)	Berhasil — ga perlu diapain	-
Media retry GENERAL_ERROR	Error umum pas download ulang media	Coba `updateMediaMessage` lagi
Media retry NOT_FOUND	Media udah ga ada di server (expired?)	Minta kirim ulang dari pengirim
Media retry DECRYPTION_ERROR	Key dekripsi salah / corrupt	Minta kirim ulang
400	Invalid media URL / ga ada directPath	Pastikan pesan beneran punya media

Pairing Errors

Kode	Penyebab	Solusi
408	QR timeout — ga discan dalam batas waktu	Minta QR/code baru
500	Gagal pairing — key mismatch	Coba ulang pairing
400	Nomor ga valid / format salah	Pastikan nomor pake format internasional tanpa +

Message Send Errors

Kode	Penyebab	Solusi
463	MessageAccountRestriction — akun kena restrict sementara	Tunggu beberapa jam. Jangan spam. Cek `fetchAccountReachoutTimelock`
479	Server nolak message karena tctoken / privacy	Biasanya auto-handle. Kalo sering, cek log
408	Upload media timeout	Coba lagi dengan `mediaUploadTimeoutMs` lebih besar
500	"All encryptions failed" — semua enkripsi gagal	Cek Signal session. Mungkin perlu re-sync session

Error Handling Best Practices

import { Boom } from '@hapi/boom'
import { DisconnectReason } from '@mataram/wa'

const handleDisconnect = async (lastDisconnect) => {
  const error = lastDisconnect?.error
  const statusCode = error?.output?.statusCode

  switch (statusCode) {
    case DisconnectReason.loggedOut:
      // Hapus session & pairing ulang
      console.error('Session expired. Pairing ulang.')
      break
    case DisconnectReason.badSession:
      // Session corrupt
      console.error('Session rusak. Hapus auth folder.')
      break
    case DisconnectReason.restartRequired:
      // Normal pas pairing — reconnect aja
      console.log('Restart required, reconnecting...')
      return true
    default:
      // Coba reconnect
      console.log('Reconnecting in 3s...')
      await delay(3000)
      return true
  }
  return false
}

sock.ev.on('connection.update', async ({ connection, lastDisconnect }) => {
  if (connection === 'close') {
    const shouldReconnect = await handleDisconnect(lastDisconnect)
    if (shouldReconnect) start()
  }
})

Debugging Tips

Set logging level: Pake logger.child({ level: 'debug' }) atau 'trace' buat liat XML stanza mentah
Reachout timelock: Panggil sock.fetchAccountReachoutTimelock() buat cek status pembatasan akun
Message capping: Panggil sock.fetchNewChatMessageCap() buat liat quota pesan
Event listener bocor: Pastikan pake ev.off() kalo listener ga dipake lagi. Double registration nulis creds dua kali
Sync waktu: Server time offset otomatis dihitung dari attribute t di response server

Pembatasan Akun

WhatsApp punya beberapa mekanisme buat nge-restrict akun yang dianggap spam. Penting buat dipahami biar bot lu ga kena silent ban.

Error 463 — SenderReachoutTimelocked

Akun kena reachout timelock. Bedanya sama banned: ini cuma sementara (biasanya 24-72 jam). WhatsApp bakal nolak pesan ke kontak baru (1:1) karena privacy token (tctoken) ga dikasih. Chat yang udah ada sebelumnya tetep aman karena udah punya tctoken.

@mataram/wa otomatis detek error ini pas nerima NACK dari server dan bakal manggil fetchAccountReachoutTimelock() buat update status. Jangan lanjut kirim pas lagi kena — retry cuma bikin makin parah.

Error 479 — SmaxInvalid (Stale Session)

Server nolak stanza karena stale device session atau alamat stanza ga bener. Biasanya muncul pas session Signal udah kedaluwarsa atau ada mismatch antara device yang terdaftar sama server. @mataram/wa auto-handle ini dengan re-create session atau kirim ulang stanza pake session yang bener.

Cek Status Pembatasan

Method	Fungsi
`sock.fetchAccountReachoutTimelock()`	Cek apakah akun kena reachout timelock, tipe pembatasan, dan kapan selesainya. Emit event `connection.update` dengan field `reachoutTimeLock`.
`sock.fetchNewChatMessageCap()`	Cek kuota chat baru per siklus. Balikin `total_quota`, `used_quota`, dan `capping_status` (NONE / FIRST_WARNING / SECOND_WARNING / CAPPED).

Message Retry Mechanism

@mataram/wa punya sistem retry otomatis buat pesan yang gagal terkirim. Config ini bisa diatur pas init socket:

Config	Default	Fungsi
`maxMsgRetryCount`	`5`	Maksimal percobaan ulang per pesan. Lewat batas ini, pesan ga bakal dicoba lagi.
`enableRecentMessageCache`	`true`	Nyimpen cache pesan terbaru di memory biar bisa di-resend pas retry. Matiin kalo lu mau hemat memory.
`enableAutoSessionRecreation`	`true`	Auto bikin ulang session Signal kalo ternyata corrupt / expired pas retry. Nyegah error 500 "All encryptions failed".

Pas retry count > 1 dan enableAutoSessionRecreation nyala, @mataram/wa otomatis ngecek session Signal ke target JID. Kalo session rusak atau ga ada, bakal di-recreate sebelum nyoba retry. Ini ngebantu banget buat menghindari spam reconnect — terutama pas error 479 (smax-invalid) yang biasanya sembuh setelah session di-recreate.

← Kembali Ke Beranda →