Meta Tech Provider

Códigos de erro da WhatsApp Cloud API

Esta é a lista de todos os códigos de erro da WhatsApp Cloud API que documentamos, numa tabela, com o significado de cada um e indicação sobre se vale a pena repetir o pedido. A maioria não vale: são determinísticos, pelo que o mesmo pedido falha da mesma forma e um ciclo de repetição transforma um pedido inválido num rate limit.

Sem armazenamento de mensagensAplicação Business + Cloud APIMCP para Claude e ChatGPTPronto em 2 minutos

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

Como ler a coluna de repetição

Tem três valores, e escolher mal entre eles é o erro mais dispendioso de toda esta referência.

Não significa que a falha seja determinística. O que falhou foi o pedido, o template ou o estado do destinatário, e enviar novamente o pedido idêntico produz o mesmo erro, consumindo entretanto throughput de que poderá precisar mais tarde. Sim significa que a falha ocorreu do lado da Meta e que um backoff resolve realmente o problema. Esperar significa que a condição é real, mas temporária: um limite ou bloqueio que desaparece por si; repetir antes disso não faz nada e pode prolongá-lo.

Porque é que a maioria destes códigos não permite repetir

Porque a plataforma devolve códigos específicos, em vez de códigos genéricos. Um parâmetro malformado, um template inexistente, uma janela de mensagens fechada e um destinatário que deixou de aceitar mensagens são situações conhecidas no momento da resposta. Por isso, a Meta identifica-as em vez de falhar de forma vaga.

Um problema no pedido não fica correto à segunda tentativa.
Um problema no template está no próprio template, que o pedido não pode alterar.
Um problema de janela ou de recusa diz respeito ao estado do destinatário, não ao seu.
Uma restrição da conta é uma decisão, e repetir não é um recurso.

O que registar quando um destes códigos surge

O suficiente para o diagnosticar sem o reproduzir, que é a diferença entre uma correção de cinco minutos e um dia de tentativas ao acaso.

A resposta de erro completa, incluindo o trace id, que é o que o apoio da Meta pede.
O corpo do pedido tal como foi enviado, não como pretendia enviá-lo. A diferença entre os dois é geralmente o erro.
O phone number id, para distinguir um problema num número de um problema em toda a conta.
O carimbo temporal, para verificar a falha face ao estado da ligação nesse momento.

Os códigos que só existem no Coexistence

São dois e confundem porque parecem falhas de envio normais. 2593107 e 2593108 dizem respeito à sincronização do histórico de conversas, o passo que copia conversas recentes da aplicação WhatsApp Business quando um número é ligado pela primeira vez.

Não são erros de mensagens e não significam que a ligação tenha falhado. Uma sincronização que exceda o limite ou decorra fora da respetiva janela deixa o número ligado e a enviar normalmente, mas com menos histórico copiado do que o esperado. Interpretá-los como uma ligação avariada leva a desligar e recomeçar, o que perde ainda mais histórico em vez de o recuperar.

Perguntas frequentes

Que erros devo repetir?

131016 e 131000, com backoff exponencial. 130429, 132015 e 133008 desaparecem por si se esperar. Todos os restantes são determinísticos.

Um código de erro significa que o meu número está desligado?

Normalmente, não. A maioria diz respeito ao pedido, ao template ou ao destinatário. Os problemas de ligação surgem como webhooks de conta e de qualidade, não como erros de envio.

O que é um trace id?

É um identificador na resposta de erro que permite ao apoio da Meta encontrar o pedido específico. Registe-o em todas as falhas; sem ele, um pedido de apoio não pode ser tratado.

Estes códigos são iguais em todos os fornecedores?

Sim. Vêm da Cloud API da Meta, por isso são idênticos, independentemente do fornecedor que ligou o número. Um fornecedor só pode alterar a clareza com que chegam até si.

Pronto para começar?

Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.

Começar período experimental gratuitoNada é cobrado durante 7 dias. Cancele quando quiser.

Continue a ler

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.