Arti Kode Error WhatsApp API dan Cara Mengatasinya

Daftar kode error WhatsApp Cloud API yang paling sering menimpa bisnis (131047, 131026, 131049, 131048, 131056, 132001, 190) beserta arti dan solusinya. Plus cara Kirimdev memetakan kode Meta ke kode yang stabil.

Kirimdev 28 Agustus 2026

error
troubleshooting
meta
api

Ringkasan singkat:

Kode error WhatsApp datang dari Meta, bukan dari Kirimdev. Angka seperti 131047 atau 131050 adalah kode mentah Cloud API.
Kirimdev memetakan angka itu ke kode teks yang stabil (outside_24h_window, marketing_opted_out) supaya penanganan error Anda tidak pecah saat Meta menggeser kodenya. Kode Meta asli tetap ada di provider_code.
Kode yang paling sering menimpa bisnis: 131047 (jendela 24 jam), 131026 (undeliverable), 131049 / 131050 (batas & opt-out marketing), 131048 (spam), 131056 (terlalu sering ke nomor sama), 132001 (template), 190 (token).
Sebelum retry, cek dulu kategorinya: gagal permanen (jangan retry), transient (retry otomatis), atau masalah akun (perbaiki dulu di Meta).

Pesan gagal terkirim di WhatsApp API sering membingungkan karena yang muncul hanya angka: 131047, 131026, 131049. Tanpa konteks, angka itu tidak memberi tahu apakah masalahnya di nomor tujuan, di template Anda, atau di akun WhatsApp Business.

Artikel ini menjelaskan kode error yang paling sering muncul, apa artinya, dan langkah konkret untuk mengatasinya. Fokusnya kode yang benar-benar sering menimpa bisnis, bukan menyalin seluruh 100+ kode dari dokumentasi Meta.

Dari mana kode error ini berasal?

Semua kode error di halaman ini berasal dari WhatsApp Cloud API milik Meta. Kirimdev adalah tech provider yang menjalankan pengiriman lewat API resmi itu, jadi ketika Meta menolak sebuah pesan, kode penolakannya diteruskan ke Anda.

Meta mengembalikan error lewat dua jalur, dan sebaiknya Anda pantau keduanya:

Respons langsung (sinkron) saat pesan dikirim ke API.
Webhook status (asinkron) beberapa saat setelahnya, di objek messages.errors.

Untuk banyak kegagalan pengiriman, status final baru diketahui lewat webhook, bukan dari respons awal. Kalau Anda hanya membaca respons pertama, sebagian kegagalan akan terlewat. Cara memantau status lewat webhook dibahas di fitur Webhooks.

Kode Meta vs kode Kirimdev

Ini pembeda yang penting. Angka mentah Meta bisa berubah makna antar versi API, dan Meta sendiri menyarankan jangan membangun logika error di sekitar angka itu. Masalahnya, angka itulah yang Anda dapat kalau memakai Cloud API langsung.

Kirimdev menambahkan satu lapisan: setiap kode Meta dipetakan ke kode teks yang stabil. Anda menulis logika penanganan error terhadap teks itu, bukan terhadap angka yang bisa bergeser.

Kode Meta	Kode Kirimdev (stabil)	Retry?
`131047`	`outside_24h_window`	Tidak, kirim template
`131050`	`marketing_opted_out`	Tidak
`131026`	`recipient_unavailable`	Tidak
`131049`	`meta_chose_not_to_deliver`	Tunggu 24 jam
`131056`	`pair_rate_limited`	Ya, ke nomor itu saja
`130429`	`account_rate_limited`	Ya, otomatis

Angka Meta aslinya tetap tersedia di field provider_code, jadi Anda tidak kehilangan detail untuk debug. Daftar lengkap pemetaannya ada di panduan kiriman gagal (docs).

Kode error yang paling sering muncul

131047: jendela 24 jam tertutup

Paling sering ditanya. Artinya lebih dari 24 jam berlalu sejak pelanggan terakhir membalas, jadi pesan teks bebas ditolak.

WhatsApp hanya mengizinkan teks bebas selama jendela layanan 24 jam terbuka. Begitu pelanggan mengirim pesan, jendela 24 jam langsung terbuka. Setelah lewat, Anda hanya boleh menghubungi mereka lewat template yang sudah Approved.

Solusi: kirim template, bukan teks biasa. Di Kirimdev kode ini muncul sebagai outside_24h_window.

131026: pesan tidak terkirim (undeliverable)

Pesan tidak bisa sampai ke penerima. Penyebab tersering:

Nomor tujuan bukan pengguna WhatsApp.
Penerima belum menyetujui Terms of Service dan Privacy Policy terbaru.
Penerima memakai versi WhatsApp yang terlalu lama.

Solusi: jangan retry membabi buta. Verifikasi bahwa nomor itu benar nomor WhatsApp aktif, lalu bersihkan daftar dari nomor mati. Kalau perlu, hubungi pelanggan lewat kanal lain dan minta mereka memperbarui aplikasi WhatsApp. Di Kirimdev: recipient_unavailable.

131049: Meta memilih tidak mengirim

Berbeda dari opt-out. Meta menahan pengiriman untuk menjaga kualitas ekosistem, paling sering karena batas jumlah template marketing per penerima per hari.

Solusi: tunggu minimal 24 jam sebelum retry template ke penerima yang sama. Retry cepat hanya menghasilkan error yang sama. Di Kirimdev: meta_chose_not_to_deliver.

131050: penerima berhenti terima marketing

Penerima menonaktifkan pesan marketing dari bisnis Anda lewat menu di aplikasi WhatsApp mereka.

Solusi: jangan kirim template marketing ke nomor itu lagi. Pantau event user_preferences lewat webhook untuk tahu kapan seseorang opt-out atau opt-in kembali. Di Kirimdev: marketing_opted_out. Aturan opt-out marketing dibahas lebih jauh di tips aman broadcast.

131048: diblokir karena spam

Pengiriman diblokir karena laporan spam meningkat atau quality rating nomor turun.

Solusi: ini sinyal kualitas, bukan sekadar teknis. Audit pengiriman terakhir Anda. Terlalu banyak block atau report dari penerima memicu error ini. Perbaiki relevansi konten dan segmentasi audiens sebelum lanjut broadcast. Di Kirimdev: spam_rate_limited.

131056: terlalu sering ke nomor yang sama

Terlalu banyak pesan antara nomor pengirim dan satu penerima dalam waktu singkat.

Solusi: perlambat pengiriman ke nomor itu saja. Nomor penerima lain tidak terpengaruh, jadi kampanye ke audiens lain boleh jalan terus. Di Kirimdev: pair_rate_limited.

132000 & 132001: masalah template

Dua kode template yang paling sering:

132000: jumlah variabel yang Anda kirim tidak cocok dengan jumlah variabel yang didefinisikan di template.
132001: template tidak ada di bahasa yang diminta, atau belum Approved.

Solusi: untuk 132000, cocokkan jumlah parameter. Untuk 132001, pastikan nama template dan kode bahasa ditulis persis sama (huruf besar/kecil dan garis bawah), lalu cek status template sudah Approved. Cara mengisi variabel template ada di panduan variabel template broadcast.

130429: throughput API tercapai

Kecepatan kirim melebihi batas throughput Meta (default sekitar 80 pesan/detik per nomor). Ini bukan kuota harian, biasanya sementara.

Solusi: kurangi kecepatan. Di Kirimdev, pacing broadcast sudah diatur otomatis supaya tidak menabrak batas ini, jadi broadcast besar berjalan bertahap. Itu normal, bukan error. Di Kirimdev kode ini muncul sebagai account_rate_limited.

190 dan 0: token bermasalah

Bukan error pengiriman, tapi error autentikasi. 190 berarti access token kedaluwarsa; 0 berarti autentikasi gagal (token dicabut atau tidak valid). Efeknya seluruh alur otomatis berhenti, bukan hanya satu pesan.

Solusi: perbarui access token di akun WhatsApp Business Anda. Kalau Anda memakai Kirimdev lewat dashboard, koneksi nomor dikelola oleh platform, jadi masalah token muncul sebagai status akun disconnected, bukan per pesan.

131042: masalah billing

Ada kendala pada metode pembayaran akun WhatsApp Business. Sering karena akun pembayaran belum ditautkan, batas kredit terlampaui, atau mata uang/zona waktu belum diatur.

Solusi: cek pengaturan billing di WhatsApp Business Manager. Ingat, Meta menagih biaya percakapan langsung ke WhatsApp Business Account Anda, bukan lewat invoice Kirimdev. Pemisahan biaya ini dibahas di tips aman broadcast.

131031 dan 368: akun dibatasi

Akun WhatsApp Business Anda dibatasi atau dinonaktifkan karena melanggar kebijakan platform. 368 khusus pelanggaran kebijakan; 131031 bisa juga berarti verifikasi data (misalnya PIN dua langkah salah).

Solusi: ini masalah level akun, bukan satu pesan. Cek pelanggaran di WhatsApp Manager dan selesaikan dulu sebelum melanjutkan pengiriman. Retry tidak akan menolong.

Tiga kategori, tiga cara respons

Sebelum menekan retry, kenali kode itu masuk kategori mana. Ini menentukan tindakan yang benar.

Kategori	Contoh kode	Yang harus dilakukan
Gagal permanen	`131026`, `131047`, `131050`, `132001`	Jangan retry. Perbaiki penyebabnya (nomor, template, jendela, opt-out)
Transient	`130429`, `131000`, `131016`	Aman di-retry. Kirimdev retry otomatis dengan backoff
Masalah akun	`190`, `131042`, `131031`, `368`	Perbaiki di WhatsApp Manager dulu. Retry per pesan percuma

Retry membabi buta pada error permanen memperburuk keadaan. Retry 131050 (opt-out) berkali-kali, misalnya, hanya menambah sinyal buruk ke reputasi nomor Anda.

Bagaimana Kirimdev mempermudah debug

Menghadapi angka mentah Meta satu per satu itu melelahkan. Kirimdev membantu di tiga titik:

Kode stabil. Setiap kode Meta dipetakan ke kode teks yang tidak berubah antar versi. Logika penanganan error Anda menempel ke teks, bukan ke angka.
Retry otomatis untuk yang transient. Error sementara di-retry dengan backoff tanpa Anda ikut campur. Yang permanen tidak di-retry supaya tidak membakar reputasi nomor.
provider_code tetap ada. Angka Meta asli disimpan, jadi Anda tetap bisa menelusuri detail saat perlu.

Kalau Anda memakai MCP server, AI bisa memanggil get_message dan langsung menjelaskan error.provider_code tanpa Anda buka dokumentasi Meta. Untuk integrasi lewat API, penanganan error dan pemetaan kode sudah ditangani TypeScript SDK.

Checklist saat pesan gagal

Baca kodenya, jangan langsung retry.
Tentukan kategorinya: permanen, transient, atau masalah akun.
Untuk permanen, perbaiki penyebab (nomor mati, template belum Approved, jendela 24 jam, opt-out).
Untuk transient, biarkan retry otomatis bekerja.
Untuk masalah akun, selesaikan di WhatsApp Manager, baru lanjut kirim.
Cek provider_code di log untuk detail kode Meta aslinya.

Bacaan lanjutan

Kiriman gagal & kode error (docs): tabel lengkap pemetaan kode Meta ke kode Kirimdev
Tips aman broadcast WhatsApp: mencegah error kualitas dan opt-out sejak awal
Perbedaan limit broadcast Kirimdev vs Meta: kenapa quota_exceeded bisa muncul
Error codes resmi Meta: referensi angka mentah

Ada kode error yang tidak Anda kenali? hello@kirimdev.com

Baca berikutnya: Tips aman broadcast · Integrasi API & webhook · Fitur Webhooks

Pertanyaan yang sering muncul

Apa arti error 131047 di WhatsApp API? Error 131047 berarti jendela layanan 24 jam sudah tertutup. Lebih dari 24 jam berlalu sejak pelanggan terakhir membalas, jadi pesan teks bebas ditolak. Solusinya kirim template yang sudah Approved untuk membuka kembali percakapan. Di Kirimdev kode ini muncul sebagai outside_24h_window.

Kenapa pesan WhatsApp saya gagal dengan error 131026? Error 131026 (message undeliverable) berarti pesan tidak bisa sampai ke penerima. Penyebab umum: nomor tujuan bukan pengguna WhatsApp, penerima belum menyetujui Terms of Service terbaru, atau memakai versi WhatsApp yang usang. Jangan retry membabi buta. Verifikasi nomornya nomor WhatsApp aktif dan bersihkan daftar dari nomor mati.

Apa beda kode error Meta dan kode error Kirimdev? Kode error Meta adalah angka mentah dari WhatsApp Cloud API (seperti 131047 atau 131050) yang bisa berubah makna antar versi. Kirimdev memetakan angka itu ke kode teks yang stabil (seperti outside_24h_window atau marketing_opted_out) supaya logika penanganan error Anda tidak pecah saat Meta menggeser kodenya. Kode mentah Meta tetap tersedia di field provider_code.

Error 131049 dan 131050 apakah sama? Beda. 131049 berarti Meta memutuskan tidak mengirim untuk menjaga kualitas ekosistem, sering karena batas jumlah template marketing per penerima per hari. Ini bukan opt-out permanen: tunggu minimal 24 jam sebelum retry. Sedangkan 131050 berarti penerima sudah berhenti berlangganan pesan marketing dari bisnis Anda. Untuk 131050 jangan kirim ulang template marketing ke nomor itu.