Giriş yapınÜcretsiz denemeyi başlatın
Meta Tech Provider

WhatsApp mesajı neden iletilemedi: failed durumu ve hata kodlarını okumak

Failed webhook'u, Meta'nın API üzerinden işletmenin gönderdiği bir mesajı gönderemediğini ya da teslim edemediğini bildirir. Bildirim messages alanında gelir; status alanı failed değerini, errors dizisi ise code, title, message, error_data.details ve href alanlarını taşır. Kod nedeni söyler: 131047 pencere kapalı, 131026 teslim edilemez, 131049 pazarlama limiti, 131050 pazarlama durduruldu, 131042 ödeme sorunu.

easyCoexistence, WhatsApp Business uygulama numaranızı Coexistence aracılığıyla Meta'nın Cloud API'sine bağlar ve failed durumlarını, doğrudan ya da otomasyonlar açıkken imzalı iletmeler olarak sunucunuza iletir.

131047

Alıcı son yanıtından bu yana 24 saatten fazla geçti; Meta'nın önerdiği çözüm bunun yerine bir şablon göndermektir.

131049

Ekosistemin sağlıklı kalması için teslim edilmedi; pazarlama şablonunu yeniden göndermeden önce en az 24 saat bekleyin.

131050

Alıcı işletmeden pazarlama mesajı almayı durdurmayı seçti; Meta yeniden denenmemesini söylüyor.

No contacts

Failed durumunda contacts dizisi bulunmaz; hatayı statuses.id üzerinden ilişkilendirin.

Delivered

Meta'nın ücretlendirdiği şey: mesajlar gönderildiğinde değil, teslim edildiğinde ücretlendirilir.

Failed durumu nasıl görünür?

Diğer durumlar gibidir, ama buna errors eklenir. contacts dizisi bulunmaz; mesaj bir telefon numarasına gönderildiyse recipient_user_id alanı atlanır ve pricing nesnesi yoktur. title ve message aynı metni taşır, error_data.details bunu bir cümleyle açıklar, href ise Meta'nın hata kodu listesine işaret eder. Bu, Meta'nın kendi örneğidir; kullanıcı başına limitle durdurulmuş bir pazarlama şablonu:

Meta's example: a message that failed with 131049
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI0QUQ2MjA4NEYyRkExNjMyREUA",
                "status": "failed",
                "timestamp": "1751142888",
                "recipient_id": "16505551234",
                "errors": [
                  {
                    "code": 131049,
                    "title": "This message was not delivered to maintain healthy ecosystem engagement.",
                    "message": "This message was not delivered to maintain healthy ecosystem engagement.",
                    "error_data": {
                      "details": "In order to maintain a healthy ecosystem engagement, the message failed to be delivered."
                    },
                    "href": "/documentation/business-messaging/whatsapp/support/error-codes"
                  }
                ]
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Hangi hata kodları en sık döner ve ne anlama gelir?

Meta hataları gönderim yanıtında, failed durumda ya da ikisinde birden döndürür; bu yüzden aynı kod size her iki yoldan da ulaşabilir ve işleyiciniz her iki yere de bakmalıdır. Aşağıda, iletilmeyen çoğu mesajı açıklayan kodlar var; her biri için Meta'nın kendi nedeni ve denenecek ilk adım yazılı. Tam liste Meta'nın hata kodu başvurusunda bulunur:

131026Undeliverable: not a WhatsApp number, terms not accepted, or an outdated WhatsApp version on the recipient's phone.
131047More than 24 hours since the customer last wrote. Send an approved template instead.
131049Held back to keep engagement healthy, usually the per-user marketing limit. Wait 24 hours or more.
131050The customer stopped marketing messages from you. Do not retry.
131042A problem with the payment method on the WhatsApp Business Account.
130472Not sent because the recipient is part of Meta's marketing message experiment.
131053Media could not be uploaded, often an unsupported file type.
131000Unknown error. Try again; if it persists, open a Direct Support ticket.

İşleyici her hata türüne nasıl tepki vermeli?

Herhangi bir yeniden denemeden önce kodu ne yapılacağına göre sınıflandırın. Her hatayı körlemesine yeniden denemek pazarlama aboneliğinden çıkmayı tekrarlayan hatalara çevirir ve bir engeli uzatabilir; geçici bir hatayı atmak ise bir dakika sonra iletilecek bir mesajı kaybettirir.

  • Kademeli artan beklemeyle yeniden deneyin: 131000 bilinmiyor, 131016 hizmet kullanılamıyor, 130429 hız sınırına ulaşıldı.
  • Önce bekleyin: 131049, en az 24 saat, çünkü erken denemeler o kullanıcıyı 24 saat daha engelleyebilir.
  • Mesajı değiştirin: 131047 için onaylı bir şablon gerekir, çünkü 24 saatlik pencere kapalıdır.
  • Bu müşteri için durdurun: 131050, bir user_preferences devam bildirimi gelene kadar.
  • Hesabı veya içeriği düzeltin: 131042 ödeme, 131031 hesap kısıtlı, 131053 medya.

Yalnızca failed durumu olarak görünen hatalar hangileri?

Bunlar, Meta'nın isteği kabul ettikten sonra karar verdiği hatalardır. Gönderim bir wamid döndürür, ret ise bu webhook'a daha sonra gelir. Meta pazarlama şablonlarını ABD telefon numarası olan WhatsApp kullanıcılarına (ABD alan kodlu +1) teslim etmez; pazarlama mesajlarını durdurmuş bir müşteriye giden pazarlama şablonu işlenir ve ardından 131050 ile başarısız olarak bildirilir; kullanıcı başına pazarlama limiti de 131049'u aynı şekilde bildirir.

Numaranın bir webhook hedefi yoksa bu hatalar görebileceğiniz hiçbir yere düşmez ve mesaj yalnızca gönderilmiş gibi görünür. Bir müşteri hiçbir şey almadığında kontrollerin tam sırası için WhatsApp API mesajları teslim edilmedi sayfasına bakın.

Coexistence numarasında ne değişir?

İki şey önemlidir. Birincisi, 24 saatlik pencere yalnızca API'yi bağlar. Meta'nın Coexistence kılavuzu, WhatsApp Business uygulamasından gönderilen mesajların müşteri hizmet penceresine tabi olmadığını söylüyor; bu yüzden 131047 sonrasında işletme sahibi o müşteriye telefondan hâlâ yanıt verebilir, sizin sisteminiz ise onaylı bir şablon gönderir.

İkincisi, hız sabittir. Uygulamada ve API'de aynı anda kullanılan bir numara saniyede en fazla 20 mesaj gönderir; bu sınırı aşmak 130429 döndürür. Geri kalan her şey herhangi bir Cloud API numarasıyla aynı görünür: aynı alan, aynı errors dizisi, aynı kodlar.

Otomasyonlar ve yapay zekanız bir hatayı nasıl görür?

Bu, Meta'nın ne zaman ret verdiğine bağlıdır. 131047 gibi gönderim anında gelen bir ret, otomasyonun adımını başarısız kılar: çalıştırma Runs sekmesinde Meta'nın mesajıyla Failed olarak görünür ve işletme sahibi o müşteriye kendisi yanıt verebilsin diye bir e-posta alır. Otomasyonlar ayrıca serbest metin bir yanıt göndermeden önce pencereyi kontrol eder ve denemek yerine window_closed ile atlar.

Meta'nın sonradan bildirdiği bir hata, Forward URL'nize ya da doğrudan hedefinize failed durum olarak gelir; çalıştırma olduğu gibi kalır. MCP bağlayıcısı üzerinden bir şablon gönderen bir yapay zeka wamid ile "sent: true" görür; wamid'in durumunu sisteminizden sorun ya da çok sayıda mesaj aynı anda başarısız olduğunda asistanın get_number_health çalıştırmasını sağlayın.

Yaygın hatalar

  • 131050'yi döngüde yeniden denemek. Müşteri pazarlama mesajlarını durdurmuş; onlar yeniden başlatana kadar her deneme aynı şekilde başarısız olur.
  • 131049 pazarlama şablonunu saatler içinde yeniden göndermek. Meta en az 24 saat ister; erken denemeler o kullanıcıyı 24 saat daha engelleyebilir.
  • Yalnızca başlığı kaydetmek. error_data.details belirli nedeni taşır; kodu ve ayrıntıyı wamid ile birlikte saklayın.
  • Webhook hedefi olmadan çalışıp teslimi yalnızca gönderim yanıtına bakarak değerlendirmek. Bu yanıt yalnızca Meta'nın mesajı kabul ettiğini söyler.
Bunu EasyCoexistence'la yapmak

Bir otomasyonun yanıtı gönderim anında reddedilirse çalıştırma Meta'nın hatasını gösterir ve e-posta alırsınız; her numara bağlantı kopmaları ve kalite düşüşleri için 7 gün 24 saat izlenir. Numara başına aylık US$ 9'dan US$ 0,75'e kadar, numara ekledikçe düşer; ilk 3 gün ücretsiz.

Sık sorulan sorular

Meta, başarısız bir mesajdan ücret alır mı?

Meta'nın fiyatlandırma sayfaları, yalnızca gönderilen değil teslim edilen mesajlar için ücret aldığını söylüyor. Failed durumunda pricing nesnesi bulunmaz. Ücretler işletmenin kendi WhatsApp Business Hesabına gider; easyCoexistence bunlara hiçbir zaman ek ücret eklemez.

131026, müşterinin işletmeyi engellediği anlamına mı gelir?

Meta'nın 131026 listesi başka nedenleri de sayar: numara WhatsApp'ta değildir, alıcı en son koşulları kabul etmemiştir ya da WhatsApp sürümü çok eskidir. Meta, bunları kontrol etmek için müşteriye başka bir kanaldan ulaşmanızı önerir.

recipient_user_id bazı hatalarda neden var, bazılarında yok?

Mesaj bir telefon numarasına gönderildiğinde Meta bunu failed durumda atlar. Müşterinin BSUID'sine gönderdiğinizde hata bunu içerir ve eksik olan recipient_id olabilir.

Bir mesaj teslim edildikten sonra başarısız olabilir mi?

Meta'nın başvurusu failed durumunu gönderilemeyen ya da teslim edilemeyen mesaj olarak tanımlar. Mesaj cihaza ulaştıktan sonra görmeyi bekleyebileceğiniz sonraki durumlar okundu veya sesli mesajlar için oynatıldı.

Okumaya devam edin

Başlamaya hazır mısınız?

WhatsApp Coexistence'ı aylar değil, dakikalar içinde kurun. Uygulama telefonda çalışmaya devam eder.

Ücretsiz denemeyi başlatın

Doğrulama tarihi