WhatsApp Cloud API Hata Kodları: Anlamları ve Çözümleri

Bu rehber, başarısız WhatsApp mesajlarıyla karşılaşan ve isteği düzeltmesi, beklemesi, mesaj türünü değiştirmesi ya da durması gerektiğini hızlıca öğrenmek isteyen geliştiriciler ve mesajlaşma operasyon ekipleri için hazırlandı. Aşağıdaki her kod, Meta'nın Cloud API hata kodu referansına göre kontrol edildi; kodlar ve ifadeler değişebilir, bu yüzden mantığı koda gömmeden önce o sayfadan teyit edin.

WhatsApp Cloud API hataları nerede görünür?

Hatalar iki yerde görünür ve ikisini de yakalamanız gerekir. İstek hataları API yanıtında hemen döner; teslimat hataları ise sonradan bir durum webhook'u ile gelir.

• Eşzamanlı hatalar. Gönderim isteği reddedilir ve yanıt, code, message, type ve çoğu zaman error_data.details içeren bir error nesnesi taşır. Tipik örnekler: süresi dolmuş token'lar, eksik parametreler ve şablon uyuşmazlıkları.
• Eşzamansız hatalar. Gönderim isteği başarılı olur ve bir mesaj kimliği döner, ancak sonradan gelen bir webhook, errors dizisiyle birlikte status: failed bildirir. Tipik örnekler: kapanmış hizmet pencereleri, teslim edilemeyen alıcılar ve pazarlama sınırları.

Sık yapılan bir hata, yalnızca HTTP yanıtını kaydetmektir. Ekipler her istek bir mesaj kimliği döndürdüğü için kampanyanın başarılı olduğunu sanır; oysa yüzlerce mesaj webhook'larda başarısız olmuştur. Durumların birbiriyle ilişkisi için gönderildi, teslim edildi, okundu ve başarısız açıklaması yazımıza bakın.

En yaygın WhatsApp hata kodları nelerdir?

Tablo, ekiplerin en sık karşılaştığı kodları, sonraki adıma göre gruplandırarak listeler. Açıklamalar Meta'nın referansından özetlenmiştir.

Başarısız kampanyaların çoğuna yol açan hatalar nasıl düzeltilir?

Pratikte birkaç kod başarısızlıkların büyük kısmına neden olur. Her birinin net bir karar kuralı vardır.

131047: hizmet penceresi kapalı

Müşteri en son 24 saatten uzun süre önce mesaj göndermiş. Serbest metin, medya ve etkileşimli mesajlara yalnızca 24 saatlik müşteri hizmetleri penceresi içinde izin verilir; pencere dışında onaylı bir şablon kullanmanız gerekir. Ayrıntılar için 24 saatlik müşteri hizmetleri penceresi yazımıza bakın. Temsilciler bu hatayla genellikle eski bir sohbeti yanıtlarken karşılaşır. Temsilcilere pencere durumunu gösterin ve süre dolduğunda bir şablon seçici sunun.

131026: mesaj teslim edilemiyor

Önce numara hijyeniyle başlayın: uluslararası biçim, doğru ülke kodu, kodun ardından baştaki sıfır olmaması. Sonra bazı numaraların WhatsApp'ta hiç olmadığını ya da eski bir uygulama sürümünde olduğunu kabul edin. OTP gibi zamana duyarlı mesajlarda SMS'e geçin. Bkz. WhatsApp, SMS ve RCS karşılaştırması.

131049 ve 131050: pazarlama sınırları ve abonelikten çıkmalar

İkisi de pazarlama mesajlarını etkiler. 131050, kullanıcının pazarlamayı durdurmak yönündeki açık tercihidir; bu kullanıcıları pazarlamadan çıkarın ve Meta'nın kullanıcı tercihleri webhook'una abone olun. 131049, Meta'nın kullanıcı etkileşimini korumak için teslim etmemeyi seçtiği anlamına gelir; Meta en az 24 saat beklemenizi önerir ve daha erken denemeler büyük olasılıkla yine başarısız olur. Yeniden göndermek yerine sıklığı azaltın ve alaka düzeyini artırın.

130429, 131048 ve 131056: çok hızlı veya çok fazla gönderim

130429 işlem hacmi sınırıdır: mesajları kuyruğa alın ve geri çekilme uygulayın. 131056 alıcı çifti düzeyindedir: tek bir kişiye çok sık mesaj gönderiyorsunuz. 131048 gönderen numaradaki bir kalite sinyalidir; yeniden deneme değil, içerik ve hedefleme düzeltmesi gerektirir. Bkz. mesajlaşma limitleri ve kalite derecelendirmesi.

132000, 132001 ve 132012: şablon uyuşmazlıkları

Bunlar neredeyse her zaman entegrasyon hatalarıdır. Şablon adı, dil kodu (örneğin ar ile en_US) ve değişken sayısı, onaylananla birebir aynı olmalıdır. Bir şablonu her düzenlediğinizde örnek değerlerle gönderen bir test oluşturun.

Uygulayabileceğiniz bir yeniden deneme politikası

Her başarısızlığı otomatik olarak sınıflandırmak için bu kontrol listesini kullanın.

1. Kodu, başlığı, error_data.details alanını, mesaj kimliğini, alıcıyı ve şablon adını kaydedin.
2. 131050, 131021, 132016, 368 ve 131031'i asla yeniden denemeyin. 368 ve 131031'i hemen bir yöneticiye bildirin.
3. Yetkilendirme (0, 190, 10), parametre (131008, 131009, 135000), şablon (132000 ile 132015 arası) ve faturalama (131042) hatalarını düzeltin, sonra yeniden deneyin. Sorumlu ekibi uyarın.
4. 130429, 4, 80007, 131016 ve 131057 için üst sınırlı üstel geri çekilmeyle bekleyip yeniden deneyin.
5. 131047 (şablon) ve 131026 (SMS veya e-posta) için kanalı ya da mesaj türünü değiştirin.
6. 131049 için 24 saat veya daha uzun bekleyin ve kampanya sıklığını gözden geçirin.
7. Başarısızlıkları kampanya raporlarında tek bir "başarısız" toplamı olarak değil, kod bazında raporlayın.

Uygulamalı örnek: Riyad'daki bir perakendecinin başarısız promosyonu

Kurgusal bir örnek. "Najd Home", izin vermiş 20.000 müşteriye bir pazarlama şablonu gönderiyor. API her isteği kabul ediyor, ancak durum webhook'ları yaklaşık 1.400 başarısızlık gösteriyor.

Koda göre gruplandırıldığında tablo net. En büyük grup 131049; ekip bu kullanıcıları sonraki iki gönderimden çıkarıyor ve haftalık sıklığı düşürüyor. Daha küçük bir grup 131026; analiz, birçok numaranın yerel baştaki sıfırla saklandığını gösteriyor ve bir normalleştirme düzeltmesi bunu çözüyor. Birkaç 131050 kullanıcısı pazarlamadan kalıcı olarak çıkarılıyor. Bazı 130429 hataları açılıştaki yoğun gönderimden kaynaklanmıştı; gönderim artık bir kuyruk üzerinden hızı ayarlanarak yapılıyor.

Sık yapılan hatalar ve dürüst sınırlar

• Her başarısızlığı yeniden denenebilir saymak. Harcamayı boşa harcar ve kaliteyi düşürebilir.
• Meta'nın metnini koda gömmek. Meta başlıkları ve açıklamaları günceller; mantığı sayısal kod üzerine kurun ve güncelleyebileceğiniz bir arama tablosu tutun.
• error_data.details alanını görmezden gelmek. Çoğu zaman hatalı parametreyi tam olarak belirtir.
• Her başarısızlığın bir çözümü yoktur. Bazı alıcılara WhatsApp'tan ulaşılamaz ve Meta her 131049 kararını açıklamaz. Alternatif bir kanal planlayın.

OmniChannels.ai nasıl yardımcı olur?

BroadNet Technologies tarafından desteklenen OmniChannels.ai, ekiplere özet ve gelişmiş görünümlerde, filtre ve CSV dışa aktarımı olan teslim raporları sunar; böylece başarısız mesajlar kampanya bazında analiz edilebilir. Kanal yedekleme (fallback), WhatsApp başarısız olduğunda mesajı RCS veya SMS üzerinden yeniden gönderebilir; şablonlar telefon önizlemesiyle gösterilir ve onay süreci boyunca izlenir, bu da uyuşmazlık hatalarını azaltır. Webhook'lar FAILED ve REJECTED durumlarını tek bir normalleştirilmiş biçimde bildirir; herkese açık geliştirici dokümanları ise bir hatalar ve limitler referansı içerir.