WhatsApp Cloud API Hata Kodları ve Anlamları

Bir WhatsApp mesajı başarısız olduğunda Meta sayısal bir hata kodu döndürür. Bu kod; isteğinizi mi, hesabınızı mı düzeltmeniz gerektiğini, beklemeniz mi yoksa o alıcıdan vazgeçmeniz mi gerektiğini söyler. Her hatayı aynı şekilde yeniden denemek mesaj limitinizi boşa harcar ve kalite puanınıza zarar verebilir. Bu yüzden bir hatanın hangi gruba girdiğini bilmek işinizi kolaylaştırır.

Bu rehber, mesaj gönderirken en çok karşılaşacağınız kodları ele alıyor. Buradaki tüm anlamlar Kasım 2026 itibarıyla Meta'nın resmi hata kodu referansından alındı. Meta zaman içinde kod ekliyor ve açıklamaları değiştiriyor; burada olmayan bir kodla karşılaşırsanız o sayfaya bakın.

Hatalar nerede görünür?

Meta'ya göre Cloud API hataları üç şekilde gelebilir:

• Senkron olarak, gönderim isteğinize verilen Graph API yanıtında. Hatalı parametre ya da token sorunlarında genellikle böyledir.
• Asenkron olarak, istek kabul edildikten sonra messages webhook'u üzerinden. Teslim hataları çoğunlukla bu yolla gelir.
• Her iki şekilde birden.

Yani gönderim isteğinize 200 yanıtı gelmesi mesajın teslim edildiği anlamına gelmez. Her iki kaynaktan gelen hata kodunu ve ayrıntıları mesaj ID'siyle birlikte kaydedin. Aksi halde "gönderildi" görünen ama hiç ulaşmamış kampanyalarla karşılaşırsınız.

Yetkilendirme ve hesap hataları

Kod	Anlamı	Ne yapmalı
0	Uygulama kullanıcısı doğrulanamadı. Token'ın süresi dolmuş ya da geçersiz kılınmış olabilir	Yeni token oluşturun
3	Yetenek (capability) ya da izin sorunu	Access Token Debugger ile token izinlerini kontrol edin
10	İzin verilmemiş ya da kaldırılmış	Yukarıdakiyle aynı. API'nin uygunluk şartlarını da kontrol edin
190	Access token'ın süresi dolmuş	Yeni token alın. Sunucular için system user token kullanın
131005	İzin verilmemiş ya da kaldırılmış	Token'da whatsapp_business_messaging ve whatsapp_business_management izinleri olduğunu doğrulayın
368	Hesap, politika ihlali nedeniyle kısıtlanmış ya da devre dışı bırakılmış	Meta'nın policy enforcement dokümanını okuyun. Yeniden denemek işe yaramaz
131031	Hesap; politika ihlali nedeniyle ya da gönderilen veriler hesapla eşleşmediği için (örneğin yanlış iki adımlı doğrulama PIN'i) kısıtlanmış	Hesabı WhatsApp Manager'da kontrol edin, Health Status API'yi değerlendirin

İstek ve parametre hataları

Bu kodlar isteğinizin hatalı olduğunu gösterir. Payload'u düzeltin; aynı isteği tekrar göndermek aynı şekilde başarısız olur.

Kod	Anlamı
100	Desteklenmeyen ya da yanlış yazılmış parametre, veya uzunluk sınırını aşan bir değer
131008	Zorunlu parametre eksik
131009	Bir ya da daha fazla parametre değeri geçersiz
131021	Gönderen ve alıcı aynı numara
131051	Desteklenmeyen mesaj türü
131053	Medya yüklenemedi; genellikle MIME türü desteklenmediği için
135000	İstek parametrelerinde genel hata. Söz dizimini kontrol edin

Alıcı ve teslim hataları

Bu hatalar kodunuzla değil, mesaj gönderdiğiniz kişiyle ilgilidir.

Kod	Anlamı	Ne yapmalı
131026	Mesaj teslim edilemedi. Numaranın WhatsApp'ta olmaması, alıcının güncel şartları kabul etmemiş olması ya da eski bir WhatsApp sürümü kullanması gibi nedenler olabilir	Numarayı doğrulayın. Döngü içinde yeniden denemeyin
131047	Alıcının son yanıtının üzerinden 24 saatten fazla geçmiş	Serbest metin yerine onaylı bir template gönderin
131049	"Sağlıklı ekosistem etkileşimini korumak için" teslim edilmedi	Meta, template'i yeniden göndermeden önce en az 24 saat beklemeyi öneriyor. Aynı kişiye üst üste göndermeyin
131050	Alıcı pazarlama mesajı almayı durdurmuş	Yeniden denemeyin. Meta, listenizi güncel tutmak için user_preferences webhook'una abone olmayı öneriyor
131052	Kullanıcının gönderdiği medya indirilemedi	error.error_data.details alanına bakın, kullanıcıdan dosyayı yeniden göndermesini isteyin
130472	Meta'nın pazarlama mesajı deneyi (experiment) kapsamında gönderilmedi	Meta'nın marketing message experiment dokümanına bakın

Ekiplerin ilk karşılaştığı hata genellikle 131047'dir. Bu bir hata değil, WhatsApp'ın 24 saatlik müşteri hizmetleri penceresi kuralıdır. 24 saat penceresi ve fiyatlandırma yazımız bunu ayrıntılı anlatıyor.

Hız sınırları (throttling)

Kod	Anlamı	Ne yapmalı
4	Uygulama API çağrı sınırına ulaştı	Yavaşlayın, artan aralıklarla (backoff) yeniden deneyin
80007	WhatsApp Business Account hız sınırına ulaştı	Aynı
130429	Cloud API mesaj kapasitesine (throughput) ulaşıldı	Daha sonra ya da daha düşük hızda gönderin
131056	Aynı göndericiden aynı alıcıya kısa sürede çok fazla mesaj	O kişiye tekrar yazmadan önce bekleyin. Diğer alıcılar etkilenmez
133016	Bir numarada çok fazla kayıt/kayıt silme denemesi	Bekleyin. Meta 72 saatte 10 denemeye izin veriyor

Yeniden denemenin mantıklı olduğu kodlar bunlardır; ama hemen değil, üstel artan bekleme süresi ve bir üst sınırla.

Template hataları (132000 serisi)

Kod	Anlamı	Ne yapmalı
132000	Parametre değeri sayısı template ile eşleşmiyor	Her {{n}} için tam olarak bir değer gönderin
132001	Template o dilde yok, onaylı değil ya da ad/dil kodu yanlış	Ad ve dil kodunun onaylı bir template ile eşleştiğini kontrol edin
132005	Çevrilmiş metin çok uzun	Çeviriyi WhatsApp Manager'da kontrol edin
132007	Template içeriği bir WhatsApp politikasını ihlal ediyor	Template inceleme kurallarını gözden geçirin
132012	Parametre değerleri yanlış biçimde	Template'te her parametre için tanımlanan biçime uyun
132015	Template düşük kalite nedeniyle duraklatıldı	Düzenleyin, onaylandıktan sonra tekrar gönderin
132016	Template çok kez duraklatıldı ve kalıcı olarak devre dışı bırakıldı	Farklı içerikle yeni bir template oluşturun

Template'leriniz daha gönderim aşamasına gelmeden reddediliyorsa WhatsApp şablonları neden reddedilir yazımıza bakın.

Hesap ve numara durumu hataları

Kod	Anlamı
131000	Bilinmeyen hata. Yeniden deneyin; devam ederse Direct Support kaydı açın
131016	Bir servis geçici olarak kullanılamıyor. WhatsApp durum sayfasını kontrol edin
131037	555 ile başlayan işletme numarasının onaylı bir görünen adı yok
131042	Ödeme yöntemi sorunu: faturalandırma ayarlarını, kredi limitini, saat dilimini ve para birimini kontrol edin
131045	Telefon numarası kayıt hatası. Önce numarayı kaydedin
131048	Çok sayıda mesaj engellendiği ya da spam olarak işaretlendiği için gönderim kısıtlandı. Kaliteyi WhatsApp Manager'da kontrol edin
131057	Hesap bakım modunda; örneğin kapasite yükseltmesi sırasında
133010	Telefon numarası kayıtlı değil

131042'ye özellikle dikkat edin. Meta artık service mesajlarını da ücretlendiriyor (fiyatlandırma yazısına bakın); bu yüzden eksik bir ödeme yöntemi trafiğinizin eskisinden çok daha büyük bir kısmını etkiler.

Basit bir yeniden deneme politikası

Hataları birkaç gruba ayırın:

Backoff ile yeniden dene:  4, 80007, 130429, 131016, 131000 (sınırlı deneme)
Bekle, sonra gönder:       131049 (24 saat), 131056 (aynı alıcı)
Yeniden deneme, düzelt:    0, 3, 10, 100, 131005, 131008, 131009, 131051,
                           132000, 132001, 132005, 132007, 132012, 133010
Yeniden deneme, listeden çıkar: 131026 (numarayı doğrula), 131050 (çıkış yapmış)
Yetkiliye ilet:            368, 131031, 131042, 131048, 132015, 132016

Gerisi kayıt tutmaktan ibaret: raporu okuyan kişinin harekete geçebilmesi için ham kodu ve mesajı her başarısız alıcıyla birlikte saklayın.

Bu kodları kampanya raporlarında görmek

Ayrıntı içermeyen "12 başarısız" sayısıyla kimse bir şey yapamaz. Mesvilo'da kampanya raporları gönderilen, teslim edilen, okunan ve başarısız sayılarını gösterir; her başarısız gönderim Meta'nın orijinal hata kodunu ve yanıtını saklar ve rapor CSV olarak dışa aktarılabilir. Böylece bir sonraki gönderimden önce 131050 çıkışlarını 131026 hatalı numaralardan kolayca ayırabilirsiniz.

Örnek bir kampanya raporunu canlı demoda açabilir ya da tüm özellikleri ürün sayfasında görebilirsiniz.

Kaynaklar

• WhatsApp error codes
• Register a business phone number
• Service messages and customer service windows