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 webhookmessage.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 dierror.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
| Kode | Arti | Endpoint yang umum trigger |
|---|---|---|
| 400 | Request tidak valid (JSON rusak, validasi body, format nomor, media gagal diunduh, API key tanpa perangkat) | semua POST |
| 401 | API Key tidak disertakan | semua |
| 403 | API Key salah / nonaktif / langganan tidak aktif | semua |
| 404 | Resource tidak ditemukan (template) atau path endpoint tidak dikenal | /messages/send-template, path salah |
| 408 | Timeout pembuatan QR | /devices/connect |
| 409 | Status perangkat: tidak terhubung, atau sesi berakhir (perlu scan QR) | kirim (hanya device_logged_out), /groups, /contacts/verify, /messages/reaction, /messages/mark-read, /messages/presence |
| 413 | Body request terlalu besar (media base64 > ±16 MB di /messages/*, atau > 100 KB di endpoint lain) | semua POST |
| 429 | Kuota bulanan habis, rate limit per API key, atau terlalu banyak auth gagal | semua |
| 500 | Error internal | semua |
| 503 | Layanan autentikasi / sesi perangkat / WhatsApp sementara tidak tersedia — coba lagi | semua (auth_unavailable), /devices/connect, /devices/disconnect, /groups, /contacts/verify |
| 504 | Layanan sesi perangkat / WhatsApp tidak menjawab tepat waktu — coba lagi | /contacts/verify, /devices/*, /groups |
Tabel Kode details.code
details.code | HTTP | Arti | Retry? |
|---|---|---|---|
api_key_missing | 401 | Header x-api-key tidak ada | ❌ perbaiki request |
invalid_api_key | 403 | API key tidak dikenal | ❌ |
api_key_inactive | 403 | API key dinonaktifkan di dashboard | ❌ |
subscription_inactive | 403 | Langganan pemilik key tidak aktif (details.status: expired, dll) | ❌ perpanjang langganan |
auth_blocked | 429 | Terlalu banyak auth gagal (5/key atau 20/IP dalam 10 menit) — blokir 30 menit | ⏳ setelah Retry-After |
auth_unavailable | 503 | Backend autentikasi sementara tidak bisa dihubungi — bukan salah key Anda | ✅ setelah Retry-After (5 dtk) |
rate_limited | 429 | Lebih dari 1.000 request/jam untuk API key ini | ⏳ setelah Retry-After |
quota_exceeded | 429 | Kuota pesan bulanan habis; Retry-After = detik sampai tanggal 1 bulan depan | ❌ upgrade / tunggu reset |
validation_error | 400 | Body tidak valid; rincian di details.errors[] | ❌ perbaiki request |
invalid_json | 400 | Body bukan JSON yang valid (mis. terpotong, kutip tidak tertutup) | ❌ perbaiki request |
media_download_failed | 400 | URL media tidak bisa diunduh; details.upstream_status bila host menjawab HTTP error | ❌ perbaiki URL |
payload_too_large | 413 | Body request melebihi batas; details.limit_bytes = batasnya | ❌ kirim media lewat URL / perkecil file |
template_not_found | 404 | template_id tidak ada / sudah dihapus | ❌ |
message_not_found | 404 | tracking_id tidak ada, lebih dari 30 hari, atau milik perangkat lain | ❌ |
idempotency_in_progress | 409 | Request dengan Idempotency-Key yang sama masih diproses | ✅ setelah Retry-After (2 dtk), key sama |
idempotency_key_mismatch | 422 | Idempotency-Key sudah dipakai untuk body yang berbeda | ❌ pakai key baru per pesan |
not_found | 404 | Path endpoint tidak dikenal | ❌ periksa URL |
plan_feature_required | 403 | Fitur butuh paket lebih tinggi (mis. Channel untuk Pro & Enterprise) | ❌ upgrade paket |
channel_not_found | 404 | Channel tidak ada atau nomor perangkat bukan pemilik/admin | ❌ cek GET /channels |
post_not_found | 404 | post_id postingan channel tidak ada | ❌ |
unsupported_media | 400 | media bukan gambar yang didukung | ❌ perbaiki URL |
media_too_large | 400 | Gambar melebihi batas ukuran | ❌ perkecil gambar |
device_not_connected | 409 | Perangkat tidak punya sesi WhatsApp aktif saat ini | ⏳ cek /devices/status |
device_logged_out | 409 | Sesi WhatsApp berakhir (logout dari HP / diblokir / pairing gagal) — perlu scan QR | ❌ hubungkan ulang |
session_service_unavailable | 503 | Layanan sesi perangkat sedang restart / tidak bisa dijangkau | ✅ beberapa detik |
verify_unavailable | 503 | WhatsApp tidak mengembalikan hasil verifikasi nomor | ✅ beberapa detik |
verify_timeout | 504 | WhatsApp tidak menjawab verifikasi dalam 15 detik | ✅ beberapa detik |
internal_error | 500 | Kesalahan 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_blockedselama 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/verifytidak 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; bilaconnecting, 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-keydihitung 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
errordi respons ini deprecated (dihapus setelah 31 Oktober 2026) — pakaimessage+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.code | Arti | Tindakan yang disarankan |
|---|---|---|
expired | Belum terkirim sampai batas expires_in — sesi perangkat di NgirimWA terputus (bukan karena HP mati) atau antrean sedang padat | Cek status perangkat di dashboard; kirim ulang bila pesannya masih relevan, atau pakai kanal lain (email/SMS) |
device_logged_out | Sesi WhatsApp perangkat berakhir (logout dari HP / diblokir) | Scan QR ulang, lalu kirim ulang |
device_not_connected | Perangkat terputus saat dikirim dan tidak kembali | Cek perangkat, kirim ulang |
not_on_whatsapp | Nomor tujuan tidak terdaftar di WhatsApp | Jangan kirim ulang; perbaiki data kontak / pakai kanal lain |
number_check_failed | WhatsApp tidak memberi jawaban saat nomor tujuan diperiksa (gangguan di sisi WhatsApp). Koneksi perangkat yang putus tidak menghasilkan kode ini — pesan seperti itu ditahan otomatis | Kirim ulang beberapa menit lagi |
recipient_restricted | WhatsApp sementara membatasi pengiriman ke nomor ini (wa_code 463) | Jangan kirim ulang beruntun; tunggu, atau minta pelanggan menghubungi Anda lebih dulu |
device_restricted | WhatsApp sementara membatasi pengiriman dari perangkat Anda (463) | Kurangi volume; tunggu masa jeda selesai |
recipient_session_error | Sesi enkripsi dengan penerima kedaluwarsa (wa_code 479) | Kirim ulang beberapa menit lagi |
wa_rejected | Ditolak WhatsApp dengan kode lain (lihat wa_code) | Kirim ulang nanti; bila berulang hubungi support dengan tracking_id |
send_timeout | Waktu tunggu pengiriman ke WhatsApp habis | Kirim ulang |
media_upload_failed | Media gagal diunggah ke WhatsApp | Kirim ulang; periksa ukuran/format file |
internal_error | Gagal karena sebab lain di sisi kami | Kirim 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');
}
}