Dlaczego wiadomość WhatsApp nie została dostarczona: status failed i jego błędy
Webhook ze statusem failed oznacza, że Meta nie mogła wysłać ani dostarczyć wiadomości wysłanej przez firmę przez API. Trafia do pola messages ze statusem failed i tablicą errors zawierającą code, title, message, error_data.details oraz href. Kod podaje przyczynę: 131047 zamknięte okno, 131026 wiadomość niedostarczalna, 131049 limit wiadomości marketingowych, 131050 marketing zatrzymany, 131042 problem z płatnością.
easyCoexistence łączy numer z aplikacją WhatsApp Business z Cloud API Meta przez Coexistence i przekazuje statusy failed na Twój serwer, bezpośrednio lub jako podpisane przekierowania, gdy automatyzacje są włączone.
Minęło ponad 24 godziny od ostatniej odpowiedzi odbiorcy; zalecenie Meta to wysłać szablon.
Nie dostarczono, aby utrzymać zdrowe zaangażowanie w ekosystemie; przed ponownym wysłaniem szablonu marketingowego odczekaj co najmniej 24 godziny.
Odbiorca zdecydował się zatrzymać wiadomości marketingowe od firmy; Meta zaleca nie ponawiać.
Status failed nie zawiera tablicy contacts, więc powiąż błąd przez statuses.id.
Meta pobiera opłaty za wiadomości dostarczone, a nie za wysłane.
Jak wygląda status failed?
Jak każdy status, plus errors. Tablica contacts jest pominięta, recipient_user_id jest pomijany, gdy wiadomość wysłano na numer telefonu, a obiekt pricing nie występuje. title i message zawierają ten sam tekst, error_data.details wyjaśnia go jednym zdaniem, a href wskazuje listę kodów błędów Meta. To przykład podany przez samą Meta: szablon marketingowy zatrzymany przez limit na użytkownika:
{
"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"
}
]
}
]
}Które kody błędów wracają najczęściej i co oznaczają?
Meta zwraca błędy w odpowiedzi na wysłanie, w statusie failed albo w obu miejscach, więc ten sam kod może dotrzeć dowolną drogą, a handler powinien czytać oba. Poniżej kody, które tłumaczą większość wiadomości, które nigdy nie docierają, z powodem podanym przez Meta i pierwszą rzeczą do sprawdzenia; pełna lista znajduje się w dokumentacji kodów błędów Meta:
Jak handler powinien reagować na każdy rodzaj błędu?
Najpierw przypisz kod do następnego kroku, zanim cokolwiek zostanie ponowione. Ślepe ponawianie zamienia rezygnację z marketingu w powtarzające się błędy i może wydłużyć blokadę, a pominięcie błędu tymczasowego gubi wiadomość, która przeszłaby minutę później:
- Ponów z opóźnieniem (backoff): 131000 nieznany, 131016 usługa niedostępna, 130429 osiągnięto przepustowość.
- Najpierw poczekaj: 131049, co najmniej 24 godziny, bo wczesne ponowienia mogą zablokować tego użytkownika na kolejne 24 godziny.
- Zmień sposób wysyłki: 131047 wymaga zatwierdzonego szablonu, ponieważ 24-godzinne okno jest zamknięte.
- Zatrzymaj dla tego klienta: 131050, dopóki nie nadejdzie zdarzenie
user_preferencesz wznowieniem. - Napraw konto lub treść: 131042 płatność, 131031 konto ograniczone, 131053 multimedia.
Które błędy pojawiają się wyłącznie jako status failed?
Te, które Meta rozstrzyga po przyjęciu żądania. Wysyłka zwraca wamid, a odmowa przychodzi później w tym webhooku. Meta nie dostarcza szablonów marketingowych do użytkowników WhatsApp z numerami telefonów w Stanach Zjednoczonych (+1 z amerykańskim kodem obszaru); szablon marketingowy wysłany do klienta, który zrezygnował z wiadomości marketingowych, jest przetwarzany, a następnie zgłaszany jako failed z kodem 131050, a limit na użytkownika zgłasza 131049 w ten sam sposób.
Jeśli numer nie ma miejsca docelowego webhooka, te błędy nie trafią nigdzie, co widać, a wiadomość po prostu wygląda na wysłaną. Pełną kolejność sprawdzeń, gdy klient niczego nie dostał, opisuje strona o wiadomościach API WhatsApp, które nie zostały dostarczone.
Co się zmienia na numerze Coexistence?
Liczą się dwie rzeczy. Po pierwsze, 24-godzinne okno dotyczy wyłącznie API. Przewodnik Meta po Coexistence mówi, że wiadomości wysłane z aplikacji WhatsApp Business nie podlegają oknu obsługi klienta, więc po błędzie 131047 właściciel nadal może odpowiedzieć klientowi z telefonu, podczas gdy Twój system wysyła zatwierdzony szablon.
Po drugie, przepustowość jest stała. Numer używany jednocześnie w aplikacji i w API wysyła co najwyżej 20 wiadomości na sekundę, a przekroczenie tego progu zwraca 130429. Wszystko inne wygląda jak na każdym numerze Cloud API: to samo pole, ta sama tablica errors, te same kody.
Jak automatyzacje i Twoje AI widzą błąd?
Zależy od tego, kiedy Meta odmawia. Odmowa w momencie wysyłki, np. 131047, przerywa krok automatyzacji: przebieg pokazuje status Failed z komunikatem Meta w zakładce Runs, a właściciel dostaje e-mail, by mógł sam odpowiedzieć klientowi. Automatyzacje sprawdzają też okno przed wysłaniem wolnej odpowiedzi i pomijają wysyłkę z window_closed zamiast próbować.
Błąd zgłoszony przez Meta później trafia jako status failed na Twój adres Forward URL lub bezpośredni cel, a przebieg pozostaje bez zmian. AI, które wysłało szablon przez konektor MCP, widzi wamid i „sent: true”; poproś system o status tego wamid albo zleć asystentowi uruchomienie get_number_health, gdy wiele wiadomości kończy się błędem naraz.
Typowe błędy
- Ponawianie 131050 w pętli. Klient zrezygnował z wiadomości marketingowych, więc każda próba kończy się tym samym błędem, dopóki klient sam tego nie zmieni.
- Ponowne wysłanie szablonu marketingowego 131049 po kilku godzinach. Meta prosi o co najmniej 24 godziny, a wczesne ponowienia mogą zablokować tego użytkownika na kolejne 24 godziny.
- Zapisywanie tylko title. error_data.details zawiera konkretny powód, więc zapisuj kod i szczegóły razem z wamid.
- Działanie bez miejsca docelowego webhooka i ocena dostarczenia na podstawie odpowiedzi na wysłanie, która mówi tylko, że Meta przyjęła wiadomość.
Gdy odpowiedź automatyzacji zostanie odrzucona w momencie wysyłki, przebieg pokazuje błąd Meta i dostajesz e-mail, a każdy numer jest monitorowany 24/7 pod kątem rozłączeń i spadków jakości. Od US$ 9 do US$ 0.75 za numer miesięcznie, cena spada wraz z dodawaniem numerów, z pierwszymi 3 dniami za darmo.
Najczęściej zadawane pytania
Czy Meta pobiera opłatę za nieudaną wiadomość?
Strony cenowe Meta mówią, że pobiera opłaty za wiadomości dostarczone, a nie za te, które są tylko wysłane. Status failed nie zawiera obiektu pricing. Opłaty trafiają na konto WhatsApp Business Account należące do firmy; easyCoexistence nie dolicza do nich żadnej marży.
Czy 131026 oznacza, że klient zablokował firmę?
Lista Meta dla 131026 wymienia inne przyczyny: numeru nie ma w WhatsApp, odbiorca nie zaakceptował najnowszych warunków albo jego wersja WhatsApp jest za stara. Meta radzi zapytać klienta innym kanałem, by to sprawdzić.
Dlaczego recipient_user_id pojawia się w niektórych błędach, a w innych nie?
Meta pomija go w statusie failed, gdy wiadomość wysłano na numer telefonu. Gdy wysłano na BSUID klienta, błąd go zawiera, a może brakować recipient_id.
Czy wiadomość może się nie udać po dostarczeniu?
Dokumentacja Meta opisuje failed jako błąd wysłania lub dostarczenia. Gdy wiadomość dotrze na urządzenie, kolejne statusy, jakich można się spodziewać, to read, a przy wiadomościach głosowych played.
Czytaj dalej
Gotowy, aby zacząć?
Skonfiguruj WhatsApp Coexistence w kilka minut, nie miesięcy. Aplikacja nadal działa na telefonie.
Rozpocznij bezpłatny okres próbnyZweryfikowano w