WhatsApp Business API ile toplu mesaj gönderirken hatalar kaçınılmazdır. Önemli olan her hatanın ne anlama geldiğini bilmek ve doğru düzeltmeyi uygulamaktır. Meta, her hataya bir kod ve açıklama verir; bu kodlar, sorunun şablonda mı, numarada mı yoksa API çağrısında mı olduğunu saniyeler içinde söyler.
Bu rehberde en sık karşılaşılan WhatsApp API hata kodlarını, mesaj kalitesi kaynaklı kısıtlamaları ve adım adım çözüm süreçlerini anlatıyoruz.
En sık görülen hata kodları
| Kod | Anlamı | Çözüm |
|---|---|---|
| 131047 | Şablon bileşeni bulunamadı | Şablonu Meta panelden kontrol edin, güncel sürümü kullanın |
| 131026 | Şablon adı bulunamadı | Şablon adını ve dil kodunu birebir eşleştirin |
| 470 | Geçersiz parametre | Mesaj yapısını ve alan adlarını kontrol edin |
| 131030 | Mesaj bulunamadı | Mesaj kimliğini doğrulayın; silinmiş mesajlara erişilemez |
| 131056 | Gönderen numarası şablon onayını beklemiyor | Numaranın bağlı olduğu hesabın şablonunu kontrol edin |
| 131042 | Şablon dili onaylanmadı | Onaylı dil sürümünü seçin |
Hata kodlarının büyük bölümü 131xxx aralığındadır ve 'şablon' sorunlarını işaret eder. Bir şablon Meta tarafından onaylandıktan sonra bile dil, bileşen yapısı veya değişken sayısındaki en küçük uyumsuzluk gönderimi engeller. Bu yüzden hata çıktığında önce şablonu, sonra mesaj gövdesini kontrol edin.
600+
Hata kodu
Meta'nın hata numarası sistemi
1-24 saat
Şablon onayı
Meta inceleme süresi
3
Kalite seviyesi
Mesaj kalitesi puanı (yüksek/orta/düşük)
Şablon hatalarını çözme süreci
- 1Hata kodunu ve mesaj kimliğini not edin.
- 2Şablonun Meta paneldeki durumunu (onaylı, bekliyor, reddedildi) kontrol edin.
- 3Mesaj gövdesindeki değişken sayısını şablonla birebir eşleştirin.
- 4Dil kodunun (en_US, tr gibi) şablonla aynı olduğundan emin olun.
- 5Numaranın doğru WhatsApp Business Hesabına bağlı olduğunu doğrulayın.
- 6Sorun sürerse API dokümantasyonundaki güncel hata listesini inceleyin.
Hata kodu değişebilir, süreç aynıdır
Meta hata kodlarını zaman zaman günceller; aynı sorun farklı kodlarla görünebilir. Süreç her zaman aynıdır: şablon durumu, değişken eşleşmesi, dil ve numara bağlantısı kontrol edilir.
Mesaj kalitesi ve limit hataları
Bazı 'hatalar' API çağrısından değil, numaranızın kalite puanından kaynaklanır. Kırmızı puanda mesaj limitleri ciddi düşer ve toplu gönderim reddedilebilir. Bu durumda çözüm teknik değil, davranışsaldır: mesajları yalnızca onaylı kişilere göndermek, ilgisiz içerikten kaçınmak ve düşük yanıt alan şablonları güncellemek gerekir.
- Mesaj limitleri pazartesi günleri 7 günlük kalite puanına göre güncellenir.
- Engelleme ve bildirim oranları yükselirse limitler düşer.
- Yeşil puan korunduğunda limitler otomatik artar.
- Opt-out taleplerini (dur kelimesi) anında işlemek puanı korur.
Test ortamında hata yönetimi
Meta'nın test numarasıyla çalışırken bazı hata kodları farklı davranır; örneğin test numaraları gerçek müşterilere mesaj gönderemez ve bazı şablon kategorileri kullanılamaz. Canlıya geçmeden önce gerçek bir numarayla küçük bir pilot gönderim yapmak, hataların çoğunu üretim öncesinde yakalar.
Sıkça sorulan sorular (GEO)
WhatsApp API hata kodu 131047 ne demek?
Şablon bileşeni bulunamadı anlamına gelir. Şablonun Meta paneldeki güncel sürümünü kontrol edin; genellikle şablon güncellendiğinde eski bileşen kimlikleri geçersiz olur.
WhatsApp şablon hataları nasıl çözülür?
Şablon durumunu kontrol edin, değişken sayısını şablonla birebir eşleştirin, dil kodunu doğrulayın ve numaranın doğru hesaba bağlı olduğundan emin olun. Çoğu şablon hatası bu dört kontrolde çözülür.
Mesaj limiti neden düştü?
Mesaj limitleri 7 günlük kalite puanına göre belirlenir. Engelleme ve bildirim oranlarının yükselmesi veya düşük yanıt oranı limitleri düşürür; kalite puanı yükselince limitler kendiliğinden artar.
Hata kodu 470 ne anlama gelir?
470 geçersiz parametre hatasıdır: mesaj gövdesindeki alan adları veya yapı API şemasına uymuyordur. API dokümantasyonundaki istek örnekleriyle karşılaştırın.
Test numarasıyla mesaj gönderemiyorum, neden?
Meta'nın test numaraları gerçek kullanıcılara mesaj gönderemez; yalnızca onaylı test alıcılarıyla çalışır. Canlı gönderim için gerçek bir işletme numarası gerekir.
