NgirimWA Docs
API

Penanganan Error

Daftar error yang mungkin muncul dari endpoint API NgirimWA, beserta penyebab dan solusinya.

Daftar error yang mungkin Anda temui dan cara mengatasinya. Ada dua jenis:

  • Error request — dijawab langsung oleh endpoint (HTTP 4xx/5xx) dan pesan tidak masuk antrean. Lihat Tabel Kode details.code.
  • Gagal kirim — request sudah diterima (200 queued), lalu pesannya gagal di belakang. Diketahui lewat Cek Status Pesan atau webhook message.failed. Lihat Kode gagal kirim.

Pembaruan 9 Oktober 2026: (1) kode baru message_not_found (404), idempotency_in_progress (409), idempotency_key_mismatch (422); (2) pesan yang gagal setelah diterima kini punya kode stabil di error.code — lihat Kode gagal kirim.

Format Respons Error

{
  "success": false,
  "message": "Deskripsi error (bahasa Inggris)",
  "details": { "code": "device_not_connected" }
}

Gunakan details.code untuk logika program; message hanya untuk manusia dan bisa berubah. Respons 429/503/504 selalu membawa header Retry-After (detik).

Ringkasan Kode HTTP

KodeArtiEndpoint yang umum trigger
400Request tidak valid (JSON rusak, validasi body, format nomor, media gagal diunduh, API key tanpa perangkat)semua POST
401API Key tidak disertakansemua
403API Key salah / nonaktif / langganan tidak aktifsemua
404Resource tidak ditemukan (template) atau path endpoint tidak dikenal/messages/send-template, path salah
408Timeout pembuatan QR/devices/connect
409Status perangkat: tidak terhubung, atau sesi berakhir (perlu scan QR)kirim (hanya device_logged_out), /groups, /contacts/verify, /messages/reaction, /messages/mark-read, /messages/presence
413Body request terlalu besar (media base64 > ±16 MB di /messages/*, atau > 100 KB di endpoint lain)semua POST
429Kuota bulanan habis, rate limit per API key, atau terlalu banyak auth gagalsemua
500Error internalsemua
503Layanan autentikasi / sesi perangkat / WhatsApp sementara tidak tersedia — coba lagisemua (auth_unavailable), /devices/connect, /devices/disconnect, /groups, /contacts/verify
504Layanan sesi perangkat / WhatsApp tidak menjawab tepat waktu — coba lagi/contacts/verify, /devices/*, /groups

Tabel Kode details.code

details.codeHTTPArtiRetry?
api_key_missing401Header x-api-key tidak ada❌ perbaiki request
invalid_api_key403API key tidak dikenal❌
api_key_inactive403API key dinonaktifkan di dashboard❌
subscription_inactive403Langganan pemilik key tidak aktif (details.status: expired, dll)❌ perpanjang langganan
auth_blocked429Terlalu banyak auth gagal (5/key atau 20/IP dalam 10 menit) — blokir 30 menit⏳ setelah Retry-After
auth_unavailable503Backend autentikasi sementara tidak bisa dihubungi — bukan salah key Anda✅ setelah Retry-After (5 dtk)
rate_limited429Lebih dari 1.000 request/jam untuk API key ini⏳ setelah Retry-After
quota_exceeded429Kuota pesan bulanan habis; Retry-After = detik sampai tanggal 1 bulan depan❌ upgrade / tunggu reset
validation_error400Body tidak valid; rincian di details.errors[]❌ perbaiki request
invalid_json400Body bukan JSON yang valid (mis. terpotong, kutip tidak tertutup)❌ perbaiki request
media_download_failed400URL media tidak bisa diunduh; details.upstream_status bila host menjawab HTTP error❌ perbaiki URL
payload_too_large413Body request melebihi batas; details.limit_bytes = batasnya❌ kirim media lewat URL / perkecil file
template_not_found404template_id tidak ada / sudah dihapus❌
message_not_found404tracking_id tidak ada, lebih dari 30 hari, atau milik perangkat lain❌
idempotency_in_progress409Request dengan Idempotency-Key yang sama masih diproses✅ setelah Retry-After (2 dtk), key sama
idempotency_key_mismatch422Idempotency-Key sudah dipakai untuk body yang berbeda❌ pakai key baru per pesan
not_found404Path endpoint tidak dikenal❌ periksa URL
plan_feature_required403Fitur butuh paket lebih tinggi (mis. Channel untuk Pro & Enterprise)❌ upgrade paket
channel_not_found404Channel tidak ada atau nomor perangkat bukan pemilik/admin❌ cek GET /channels
post_not_found404post_id postingan channel tidak ada❌
unsupported_media400media bukan gambar yang didukung❌ perbaiki URL
media_too_large400Gambar melebihi batas ukuran❌ perkecil gambar
device_not_connected409Perangkat tidak punya sesi WhatsApp aktif saat ini⏳ cek /devices/status
device_logged_out409Sesi WhatsApp berakhir (logout dari HP / diblokir / pairing gagal) — perlu scan QR❌ hubungkan ulang
session_service_unavailable503Layanan sesi perangkat sedang restart / tidak bisa dijangkau✅ beberapa detik
verify_unavailable503WhatsApp tidak mengembalikan hasil verifikasi nomor✅ beberapa detik
verify_timeout504WhatsApp tidak menjawab verifikasi dalam 15 detik✅ beberapa detik
internal_error500Kesalahan tak terduga di sisi kami✅ sekali, lalu hubungi support

Detail per error di bawah.

API Key Tidak Disertakan

{
  "success": false,
  "message": "API Key is required",
  "details": { "code": "api_key_missing" }
}

Status Code: 401

Solusi: pastikan header x-api-key ada di request. Kegagalan ini dihitung terhadap proteksi auth (lihat di bawah) — jangan biarkan job berulang tanpa header.

API Key Tidak Valid / Langganan Tidak Aktif

Respon (salah satu)

{ "success": false, "message": "Invalid API Key", "details": { "code": "invalid_api_key" } }
{ "success": false, "message": "API Key is inactive", "details": { "code": "api_key_inactive" } }
{ "success": false, "message": "Your subscription has expired. Please renew your subscription to continue using the API.", "details": { "code": "subscription_inactive", "status": "expired" } }
{ "success": false, "message": "Your subscription is not active. Please renew your subscription to continue using the API.", "details": { "code": "subscription_inactive", "status": "inactive" } }

Status Code: 403

Penyebab:

  • API Key salah atau sudah dinonaktifkan di dashboard
  • Langganan akun pemilik API Key kedaluwarsa / belum aktif

Solusi:

  • Periksa API Key di dashboard
  • Perpanjang langganan

API key yang salah selalu dijawab 403, berapa kali pun diulang. Setelah 5 kegagalan (key salah/nonaktif atau header hilang) dalam 10 menit untuk key yang sama — atau 20 kegagalan dari IP klien yang sama — request berikutnya dijawab 429 auth_blocked selama 30 menit. Langganan yang tidak aktif tidak dihitung sebagai kegagalan auth. Jangan retry otomatis pada 401/403.

Terlalu Banyak Auth Gagal

{
  "success": false,
  "message": "Too many failed requests. Please try again later.",
  "details": { "code": "auth_blocked", "retry_after": 1734 }
}

Status Code: 429 (+ header Retry-After)

Solusi: hentikan job yang memakai key/header salah, tunggu Retry-After detik, lalu lanjutkan dengan key yang benar.

Layanan Autentikasi Sementara Tidak Tersedia

{
  "success": false,
  "message": "Authentication service is temporarily unavailable. Please retry in a few seconds.",
  "details": { "code": "auth_unavailable", "retry_after": 5 }
}

Status Code: 503 (+ Retry-After: 5)

Penyebab: backend kami tidak bisa memverifikasi API key karena database autentikasi sementara tidak bisa dihubungi. Bukan berarti key Anda salah, dan tidak dihitung sebagai kegagalan auth.

Solusi: ulangi request setelah beberapa detik (back-off). Aman untuk di-retry dengan Idempotency-Key yang sama.

API Key Tidak Terhubung ke Perangkat

{
  "success": false,
  "message": "API Key does not have an associated device"
}

Status Code: 400

Solusi: buat API Key baru dan pilih perangkat, atau pasangkan perangkat pada API Key di dashboard.

Kuota Pesan Habis

Respon:

{
  "success": false,
  "message": "Monthly message quota has been exceeded. Please upgrade your plan or purchase additional quota to continue sending messages.",
  "details": { "code": "quota_exceeded" }
}

Status Code: 429 (+ Retry-After = detik sampai tanggal 1 bulan depan)

Penyebab:

  • Kuota bulanan habis

Solusi:

  • Upgrade paket langganan atau beli kuota tambahan
  • Tunggu reset kuota bulan depan (tanggal 1)

Berlaku untuk semua endpoint kirim termasuk /messages/reaction. /messages/mark-read, /messages/presence, dan /contacts/verify tidak memakai kuota.

Bila sistem kami sementara tidak bisa membaca kuota Anda (gangguan database), request tetap diproses — Anda tidak akan ditolak karena gangguan di sisi kami.

Perangkat Tidak Terhubung

Respon:

{
  "success": false,
  "message": "WhatsApp device is not connected",
  "details": { "code": "device_not_connected" }
}

Status Code: 409

Endpoint yang menjawab ini: GET /groups, POST /contacts/verify, POST /messages/reaction, POST /messages/mark-read, POST /messages/presence — operasi yang memerlukan socket WhatsApp hidup saat itu juga.

Endpoint kirim (/messages/send, /send-template, /quick-reply, /interactive, /buttons, /list, /carousel) tidak menjawab error ini. Pesan diproses lewat antrean: bila perangkat hanya terputus sesaat (gangguan singkat / restart), request tetap diterima (200, data.status: "queued") dan dikirim saat koneksi pulih (paling lama sampai expires_in, default 1 jam) — hasil akhirnya bisa dicek lewat Cek Status Pesan atau webhook message.sent / message.failed.

Penyebab:

  • Koneksi perangkat sedang terputus (gangguan singkat / restart)

Solusi:

  • Cek /devices/status; bila connecting, tunggu beberapa detik dan coba lagi
  • Bila disconnected, hubungkan perangkat via dashboard atau /devices/connect

Sesi Perangkat Berakhir

{
  "success": false,
  "message": "WhatsApp session for this device has ended. Re-link the device by scanning the QR code.",
  "details": { "code": "device_logged_out" }
}

Status Code: 409

Endpoint yang menjawab ini: semua endpoint kirim (ditolak di depan karena tidak mungkin terkirim) dan endpoint lain yang memerlukan sesi.

Penyebab: perangkat logout dari HP, diblokir WhatsApp, atau pairing tidak selesai. Tidak akan pulih sendiri.

Solusi: scan QR ulang via dashboard atau /devices/connect.

Format Nomor Tidak Valid

Respon

{ "success": false, "message": "Invalid phone number format: too short", "details": { "code": "validation_error" } }
{ "success": false, "message": "Invalid phone number format: too long", "details": { "code": "validation_error" } }

Status Code: 400

Penyebab:

  • Nomor kurang dari 8 atau lebih dari 15 digit setelah karakter non-digit dibuang

Solusi:

  • Gunakan format: 628123456789, 08123456789, 8123456789, atau nomor internasional lengkap dengan kode negara (14155551234). Aturan ini sama di semua endpoint, termasuk /contacts/verify.

Validasi Body Gagal

{
  "success": false,
  "message": "Validation Error",
  "details": {
    "code": "validation_error",
    "errors": [{ "field": "body.to", "message": "Required" }]
  },
  "error": "[{\"field\":\"body.to\",\"message\":\"Required\"}]"
}

Status Code: 400

Gunakan details.errors (array { field, message }). Field error berisi string JSON yang sama — deprecated, masih dikirim sampai 31 Oktober 2026 untuk klien lama yang memakai JSON.parse(body.error).

Media Tidak Bisa Diunduh

{
  "success": false,
  "message": "Failed to download media from URL: the media host answered HTTP 404",
  "details": { "code": "media_download_failed", "upstream_status": 404 }
}

Status Code: 400

Penyebab: URL media tidak bisa diakses dari server kami — host menjawab error (details.upstream_status), tidak dapat dijangkau, atau timeout (30 detik).

Solusi: pastikan URL publik (HTTPS), tidak butuh login, dan merespons cepat; atau kirim media sebagai data-URI base64 (maks. ±16 MB per file).

Body Request Terlalu Besar

{
  "success": false,
  "message": "Request body too large. Send large media as a URL in \"media\" instead of base64, or compress it (max 16 MB per file).",
  "details": { "code": "payload_too_large", "limit_bytes": 26214400 }
}

Status Code: 413

Penyebab: media base64 di field media membuat body melebihi batas — 25 MB untuk endpoint /messages/* (file ±16 MB), 100 KB untuk endpoint lain.

Solusi:

  • Kirim file lewat URL di field media (tidak terkena batas body), atau
  • Perkecil file — mis. ubah audio WAV hasil text-to-speech ke MP3/OGG, kompres gambar.

JSON Tidak Valid

{
  "success": false,
  "message": "Invalid JSON body",
  "details": { "code": "invalid_json" }
}

Status Code: 400

Penyebab: body request bukan JSON yang valid — biasanya string terpotong, kutip tidak tertutup, atau ekspresi n8n yang menyisipkan teks mentah ke dalam JSON.

Solusi: pastikan header Content-Type: application/json dan body lolos validator JSON. Di n8n, pakai mode JSON dengan ekspresi {{ JSON.stringify(...) }} untuk nilai yang berisi teks bebas.

Template Tidak Ditemukan

Respon

{
  "success": false,
  "message": "Template not found",
  "details": { "code": "template_not_found" }
}

Status Code: 404

Penyebab:

  • Template ID salah
  • Template sudah dihapus

Solusi:

  • Periksa template ID di dashboard
  • Buat template baru jika diperlukan

Endpoint Tidak Dikenal

{
  "success": false,
  "message": "Endpoint not found: POST /api/v1/messages/sned",
  "details": { "code": "not_found" }
}

Status Code: 404

Solusi: periksa method dan path. Semua path yang tidak dikenal di bawah /api dijawab JSON seperti di atas (bukan halaman HTML).

Rate Limit Terlampaui

Respon

{
  "success": false,
  "message": "Too many requests, please try again later.",
  "details": { "code": "rate_limited" },
  "error": "Too many requests, please try again later."
}

Status Code: 429 (+ Retry-After)

Penyebab:

  • Lebih dari 1.000 request per jam untuk API key yang sama (request tanpa x-api-key dihitung per IP klien)

Solusi:

  • Tunggu reset window (lihat header RateLimit-Reset / Retry-After)
  • Kurangi frekuensi request
  • Implementasikan queue / debounce untuk pengiriman massal
  • Bila sistem yang berbeda memang butuh kuota terpisah, buat API key terpisah per sistem

Field error di respons ini deprecated (dihapus setelah 31 Oktober 2026) — pakai message + details.code.

Layanan Sesi Perangkat Tidak Tersedia

{
  "success": false,
  "message": "Device session service is temporarily unavailable. Please retry shortly.",
  "details": { "code": "session_service_unavailable" }
}

Status Code: 503 (+ Retry-After)

Muncul di /devices/connect, /devices/disconnect, /groups, /contacts/verify saat layanan sesi perangkat sedang restart atau tidak bisa dijangkau. Varian 504 Device session service timed out. Please retry. berarti layanan ada tetapi tidak menjawab tepat waktu. Keduanya aman di-retry setelah beberapa detik.

Verifikasi Nomor Gagal

{ "success": false, "message": "WhatsApp did not return verification results. Please retry.", "details": { "code": "verify_unavailable" } }
{ "success": false, "message": "Timed out verifying numbers with WhatsApp. Please retry.", "details": { "code": "verify_timeout" } }

Status Code: 503 / 504 (+ Retry-After)

Khusus POST /contacts/verify. Sebelumnya kondisi ini dijawab 200 dengan semua nomor exists: false (false negative) — sekarang dijawab error supaya Anda tidak menghapus kontak yang sebenarnya valid. Ulangi request beberapa detik kemudian.

Kode gagal kirim (status failed)

Muncul di error.code pada Cek Status Pesan dan pada webhook message.failed (message.error.code). Kode ini stabil — aman untuk dipakai sebagai percabangan di kode Anda. wa_code berisi kode mentah WhatsApp bila kegagalannya datang dari WhatsApp.

error.codeArtiTindakan yang disarankan
expiredBelum terkirim sampai batas expires_in — sesi perangkat di NgirimWA terputus (bukan karena HP mati) atau antrean sedang padatCek status perangkat di dashboard; kirim ulang bila pesannya masih relevan, atau pakai kanal lain (email/SMS)
device_logged_outSesi WhatsApp perangkat berakhir (logout dari HP / diblokir)Scan QR ulang, lalu kirim ulang
device_not_connectedPerangkat terputus saat dikirim dan tidak kembaliCek perangkat, kirim ulang
not_on_whatsappNomor tujuan tidak terdaftar di WhatsAppJangan kirim ulang; perbaiki data kontak / pakai kanal lain
number_check_failedWhatsApp tidak memberi jawaban saat nomor tujuan diperiksa (gangguan di sisi WhatsApp). Koneksi perangkat yang putus tidak menghasilkan kode ini — pesan seperti itu ditahan otomatisKirim ulang beberapa menit lagi
recipient_restrictedWhatsApp sementara membatasi pengiriman ke nomor ini (wa_code 463)Jangan kirim ulang beruntun; tunggu, atau minta pelanggan menghubungi Anda lebih dulu
device_restrictedWhatsApp sementara membatasi pengiriman dari perangkat Anda (463)Kurangi volume; tunggu masa jeda selesai
recipient_session_errorSesi enkripsi dengan penerima kedaluwarsa (wa_code 479)Kirim ulang beberapa menit lagi
wa_rejectedDitolak WhatsApp dengan kode lain (lihat wa_code)Kirim ulang nanti; bila berulang hubungi support dengan tracking_id
send_timeoutWaktu tunggu pengiriman ke WhatsApp habisKirim ulang
media_upload_failedMedia gagal diunggah ke WhatsAppKirim ulang; periksa ukuran/format file
internal_errorGagal karena sebab lain di sisi kamiKirim ulang sekali; bila berulang hubungi support dengan tracking_id

Kode baru bisa ditambahkan di masa depan — perlakukan kode yang tidak dikenal seperti internal_error.

Tips Penanganan Error

try {
  const res = await axios.post(url, body, { headers });
  console.log(res.data.data.status);      // "queued"
  console.log(res.data.data.tracking_id); // simpan — hasil akhir lewat GET /messages/:tracking_id atau webhook
} catch (error) {
  const status = error.response?.status;
  const code = error.response?.data?.details?.code;
  const retryAfter = Number(error.response?.headers?.['retry-after'] || 5);

  if (code === 'auth_unavailable' || code === 'session_service_unavailable' ||
      code === 'verify_unavailable' || code === 'verify_timeout') {
    await sleep(retryAfter * 1000); // aman di-retry dengan Idempotency-Key yang sama
  } else if (code === 'rate_limited' || code === 'auth_blocked') {
    await sleep(retryAfter * 1000);
  } else if (code === 'quota_exceeded') {
    console.log('Kuota bulan ini habis — upgrade atau tunggu tanggal 1');
  } else if (code === 'device_logged_out') {
    console.log('Perangkat perlu scan QR ulang');
  } else if (code === 'device_not_connected') {
    console.log('Perangkat sedang offline — cek /devices/status');
  } else if (code === 'idempotency_in_progress') {
    await sleep(retryAfter * 1000); // ulangi dengan Idempotency-Key yang SAMA
  } else if (status === 400) {
    console.log('Periksa format data Anda', error.response.data.details?.errors);
  } else if (status === 401 || status === 403) {
    console.log('API Key / langganan bermasalah — jangan retry otomatis');
  }
}

On this page