Meta Tech Provider

Kody błędów WhatsApp Cloud API

To wszystkie udokumentowane przez nas kody błędów WhatsApp Cloud API, zebrane w jednej tabeli wraz ze znaczeniem i informacją, czy ponowienie żądania pomoże. Większość nie pomoże: błędy są deterministyczne, więc to samo żądanie kończy się tak samo, a pętla ponowień zmienia nieprawidłowe żądanie w przekroczenie limitu.

Bez przechowywania wiadomościAplikacja firmowa + Cloud APIMCP dla Claude i ChatGPTGotowe w 2 minuty

Request

Code	What it means	Retry
100	A parameter is unsupported, misspelled or malformed.	No
131008	A required parameter was not included at all.	No
131009	A parameter is present with a value the endpoint rejects.	No
131021	Sender and recipient are the same number.	No
131051	The message type is not supported, often a Coexistence limit.	No
131052	Meta could not download media a customer sent.	No
131053	Meta could not upload media you sent. Size, format or reach.	No

Template

Code	What it means	Retry
132000	The number of parameters does not match the template.	No
132001	No template exists with that name and language pair.	No
132007	The template breaks messaging policy. Rewrite and resubmit.	No
132012	Parameter format does not match what the template defines.	No
132015	The template is paused after a quality decline. Temporary.	Wait
132016	The template is permanently disabled. It will not come back.	No

Window and recipient

Code	What it means	Retry
131047	The 24-hour service window is closed. Send a template.	No
131026	The recipient cannot receive the message at all.	No
131050	The person opted out. There is no workaround, by design.	No
130497	Messaging that country is restricted for your account.	No

Registration and PIN

Code	What it means	Retry
131045	The number was never registered for Cloud API messaging.	No
133010	The number is not registered. Registration must be completed.	No
133006	The number must be verified before it can be registered.	No
133005	The two-step verification PIN was wrong. Stop guessing.	No
133008	Too many PIN attempts. Registration is locked for a period.	Wait

Access and account

Code	What it means	Retry
190	The access token expired or was invalidated.	No
368	The account is restricted after a policy violation.	No
131031	The account is restricted, or its data does not match Meta's.	No
131042	A payment problem on the business account blocks sending.	No
131049	Meta blocked the message to protect ecosystem health.	No

Rate limits

Code	What it means	Retry
130429	The account's messaging throughput limit was reached.	Wait
131048	A spam rate limit was hit. Quality, not volume, is the cause.	No
131056	Too many messages between your number and one recipient.	No
80007	The account hit its management call limit. Usually polling.	Wait

Transient

Code	What it means	Retry
131016	A Meta service is temporarily unavailable.	Yes
131000	Unclassified failure. Retry once, then escalate with the trace id.	Yes

Coexistence sync

Code	What it means	Retry
2593107	The chat history synchronisation limit was exceeded.	No
2593108	A sync was attempted outside the 24-hour sync window.	No

Jak czytać kolumnę ponowienia

Zawiera trzy wartości, a błędny wybór między nimi jest najkosztowniejszą pomyłką w całym tym zestawieniu.

„Nie” oznacza, że błąd jest deterministyczny. Nie powiodło się żądanie, szablon lub stan odbiorcy, a ponowne wysłanie identycznego żądania wywoła ten sam błąd i zużyje przepustowość potrzebną później. „Tak” oznacza, że błąd leżał po stronie Meta i właściwe opóźnienie rzeczywiście go rozwiązuje. „Poczekaj” oznacza, że przyczyna jest rzeczywista, lecz tymczasowa: to limit lub blokada, która znika samoistnie. Ponowienie przed jej usunięciem nic nie daje i może ją przedłużyć.

Dlaczego większości z nich nie należy ponawiać

Ponieważ platforma zwraca konkretne kody zamiast ogólnych. Nieprawidłowy parametr, nieistniejący szablon, zamknięte okno wiadomości i odbiorca, który zrezygnował z otrzymywania wiadomości, są znane w chwili udzielenia odpowiedzi, więc Meta nazywa je wprost, zamiast kończyć żądanie niejasnym błędem.

Problem z żądaniem nie stanie się poprawny przy drugiej próbie.
Problem z szablonem tkwi w szablonie, którego żądanie nie może zmienić.
Problem z oknem lub rezygnacją odbiorcy dotyczy jego stanu, nie Twojego.
Ograniczenie konta jest decyzją, a ponowienie żądania nie jest odwołaniem.

Co rejestrować po otrzymaniu jednego z tych kodów

Tyle, by zdiagnozować problem bez jego odtwarzania. To różnica między pięciominutową naprawą a całym dniem zgadywania.

Pełną odpowiedź z błędem, w tym trace id, o które prosi pomoc Meta.
Treść żądania w wysłanej postaci, nie w zamierzonej. Różnica między nimi jest zwykle źródłem problemu.
Identyfikator numeru telefonu, aby odróżnić problem jednego numeru od problemu całego konta.
Znacznik czasu, aby sprawdzić błąd względem stanu połączenia w danym momencie.

Kody występujące tylko w Coexistence

Są dwa i powodują zamieszanie, bo wyglądają jak zwykłe błędy wysyłania. 2593107 i 2593108 dotyczą synchronizacji historii czatów, czyli etapu kopiowania ostatnich rozmów z aplikacji WhatsApp Business po pierwszym połączeniu numeru.

Nie są to błędy wiadomości i nie oznaczają nieudanego połączenia. Jeśli synchronizacja przekroczy limit lub odbędzie się poza wyznaczonym oknem, numer pozostanie połączony i będzie normalnie wysyłać wiadomości, ale skopiuje się mniej historii, niż oczekiwano. Odczytanie tych kodów jako zerwanego połączenia prowadzi do odłączenia numeru i rozpoczęcia od nowa, co powoduje utratę większej części historii zamiast jej odzyskania.

Najczęściej zadawane pytania

Które błędy należy ponawiać?

131016 i 131000, z wykładniczym zwiększaniem opóźnienia. 130429, 132015 i 133008 znikają samoistnie po odczekaniu. Wszystkie pozostałe są deterministyczne.

Czy kod błędu oznacza, że mój numer jest odłączony?

Zwykle nie. Większość tych kodów dotyczy żądania, szablonu lub odbiorcy. Problemy z połączeniem pojawiają się jako webhooki konta i jakości, a nie jako błędy wysyłania.

Czym jest trace id?

To identyfikator w odpowiedzi z błędem, który pozwala pomocy Meta znaleźć konkretne żądanie. Rejestruj go przy każdym błędzie, bo bez niego nie da się skutecznie obsłużyć zgłoszenia.

Czy te kody są takie same u każdego dostawcy?

Tak. Pochodzą z Cloud API Meta, więc są identyczne niezależnie od dostawcy, który połączył numer. Dostawca może jedynie zmienić sposób, w jaki do Ciebie docierają.

Gotowy, aby zacząć?

Skonfiguruj WhatsApp Coexistence w kilka minut, nie miesięcy. Aplikacja nadal działa na telefonie.

Rozpocznij bezpłatny okres próbnyPrzez 7 dni nic nie zapłacisz. Anuluj w dowolnym momencie.

Czytaj dalej

ReferenceWhatsApp error 131047: re-engagement messageError 131047 means more than 24 hours have passed since that customer last messaged you, so the customer service window is closed and free text will not deliver.ReferenceWhatsApp error 100: invalid parameterError 100 means the request carried a parameter Meta does not accept: unsupported, misspelled, or the wrong shape for that endpoint.ReferenceWhatsApp error 131016: service unavailableError 131016 means a service on Meta's side is temporarily unavailable.ReferenceA number stopped working: how to find out whyWhen a connected number stops working, the cause is almost never the code.ReferenceWhatsApp webhook fields, and which ones go whereA WhatsApp Business Account delivers events as named fields.GuideWhatsApp Coexistence: the app and the API on one numberCoexistence is Meta's official mode for running the WhatsApp Business app and the Cloud API on one number at the same time.