Criar conta
← Blog

·

Erro 131026 na API do WhatsApp: mensagem não entregue, causas e o que fazer

Atualizado em 29/10/2026

O erro 131026 da API do WhatsApp significa “Unable to deliver message”: a Meta aceitou o envio, mas não conseguiu entregar a mensagem ao destinatário. A documentação oficial aponta três causas possíveis: o número não tem WhatsApp, a pessoa não aceitou os Termos de Serviço e a Política de Privacidade mais recentes, ou ela usa uma versão antiga do aplicativo. Reenviar a mesma mensagem não resolve; o caminho é confirmar o contato por outro canal e ajustar a sua base.

Este artigo aprofunda só o 131026. A tabela geral com os outros códigos está em Erros da API do WhatsApp.

O que a Meta diz sobre o erro 131026

Na tabela oficial de códigos de erro, o 131026 aparece com a descrição “Unable to deliver message” e três motivos:

Causa listada pela MetaO que significa na prática
O número do destinatário não é um número de WhatsAppNúmero inexistente, digitado errado ou que nunca teve conta no WhatsApp
O destinatário não aceitou os novos Termos de Serviço e a Política de PrivacidadeA conta existe, mas está pendente de aceite no aplicativo
O destinatário usa uma versão antiga do WhatsAppO app está abaixo da versão mínima exigida

As versões mínimas citadas na documentação são:

PlataformaVersão mínima
Android e app WhatsApp Business para Android2.21.15.15
iOS e app WhatsApp Business para iOS2.21.170.4
KaiOS2.2130.10
WhatsApp Web2.2132.6

A solução oficial é toda feita fora do WhatsApp. A Meta orienta pedir ao usuário, por outro canal, que:

  1. confirme que consegue enviar uma mensagem para o seu número comercial;
  2. aceite os termos mais recentes, que o aplicativo apresenta no menu de configurações (a documentação cita Settings > Help e Settings > Application information);
  3. atualize o WhatsApp para a versão mais recente.

Um ponto importante: a API não informa qual das três causas aconteceu. O código é o mesmo para todas.

E o bloqueio? Onde ele entra

Muita lista na internet coloca “o usuário bloqueou a empresa” como causa do 131026. A tabela de erros não diz isso. O bloqueio aparece em outra página, a de suporte da Cloud API, na seção sobre mensagens que ficam como enviadas mas não são entregues. Ali a Meta lista:

  • o usuário não ficou online durante os 30 dias em que a Meta guarda mensagens para quem está offline;
  • o cliente bloqueou o número comercial, ou outro número comercial da mesma empresa;
  • o cliente está em um país restrito ou sancionado.

A mesma página avisa que, em muitos desses casos, a Meta não revela a causa. Por isso, trate bloqueio como uma hipótese de “enviado sem entrega”, e não como um significado do 131026. A página também cita casos em que a API devolve código de erro, como termos não aceitos e versão desatualizada, que são justamente duas das causas do 131026.

Quer testar enquanto lê? Crie sua conta na Vectalk e envie a primeira mensagem pela API oficial. Criar conta grátis →

Onde o 131026 aparece

O 131026 chega de forma assíncrona, no webhook messages, como um status failed com o array errors. A resposta da chamada de envio pode ter vindo com sucesso e um wamid; a falha vem depois. Um exemplo do evento:

{
  "statuses": [
    {
      "id": "wamid.HBgLNTU4NDk5OTk5OTk5...",
      "status": "failed",
      "timestamp": "1761750000",
      "recipient_id": "5584999999999",
      "errors": [
        {
          "code": 131026,
          "title": "Unable to deliver message.",
          "message": "Unable to deliver message.",
          "error_data": {
            "details": "Unable to deliver message."
          }
        }
      ]
    }
  ]
}

Os textos de title e details podem variar. Construa a lógica em cima do code. O ciclo completo de status (sent, delivered, read, failed) está explicado em status de mensagem via webhook, e o diagnóstico de mensagens que param em sent está em mensagem enviada mas não entregue.

Como diferenciar as causas

A API não diferencia, mas o seu histórico ajuda. Algumas pistas práticas, que são inferência a partir dos seus próprios dados e não uma regra da Meta:

O que o seu sistema sabeCausa mais provávelO que fazer
O contato nunca mandou mensagem para você e o número veio de formulário digitadoNúmero sem WhatsApp ou digitado erradoConfirmar o número por e-mail ou SMS; corrigir o cadastro
O contato já conversou com você pelo WhatsApp antesTermos pendentes ou app desatualizadoAvisar por outro canal para atualizar o app e aceitar os termos
Outras mensagens para o mesmo contato foram entregues ontemSituação temporária do lado do usuárioPausar envios para ele e tentar de novo mais tarde, uma vez
O número tem formato estranho (faltando código do país, dígitos a mais)Erro de cadastroNormalizar no formato internacional, só dígitos, com código do país

Se o contato já conversou com sua empresa, o número teve WhatsApp em algum momento. Isso torna a primeira causa menos provável e aponta para termos ou versão do app.

Quando não reenviar

A regra geral: não reenvie em loop. O 131026 não é um erro temporário de infraestrutura, como o 131000 ou o 130429. Ele depende de algo que só o usuário resolve (ter WhatsApp, aceitar termos, atualizar o app).

  • Não coloque o 131026 na fila de nova tentativa com espera exponencial.
  • Não dispare o mesmo template de novo no mesmo dia.
  • Não troque de template achando que o conteúdo é o problema. O código não é sobre conteúdo.
  • Pode tentar uma vez mais tarde (dias depois) se houver sinal de que o usuário resolveu, por exemplo, depois que ele confirmou por e-mail que atualizou o app.
  • Pode voltar a enviar normalmente quando o próprio contato mandar mensagem para você, porque isso prova que o WhatsApp dele está funcionando.

Custo: mensagem com 131026 é cobrada?

Não. A página de preços da Meta diz que a empresa só é cobrada quando a mensagem é entregue. Uma mensagem que termina em failed com 131026 não foi entregue.

O custo real é outro: tempo do time, campanhas com alcance menor que o planejado e uma base cada vez mais suja. Em uma campanha de marketing com tarifa de R$ 0,3217 por mensagem entregue (destino Brasil, desde 1º/10/2026), números que falham não pesam no orçamento, mas distorcem a previsão se você calcula o custo pelo tamanho da lista.

Fallback: SMS e e-mail

Como a própria Meta orienta resolver por canal fora do WhatsApp, vale ter um fallback automático para mensagens importantes:

  • Transacional (pedido, pagamento, código): se o status for failed com 131026, envie o mesmo aviso por SMS ou e-mail. Para códigos de verificação, ter um fallback por SMS evita que o usuário fique travado no login. Comparamos os dois canais em WhatsApp ou SMS.
  • Marketing: não force outro canal só porque o WhatsApp falhou. Use o e-mail apenas se a pessoa também autorizou esse canal.
  • Mensagem de reativação: um e-mail curto pedindo que a pessoa confirme o número, atualize o WhatsApp, aceite os termos e mande um “oi” para o seu número cobre as três orientações da Meta de uma vez. Se o “oi” chegar, ele ainda abre a janela de atendimento.

Limpeza de base

O 131026 é um bom termômetro da qualidade da sua lista. Uma rotina simples:

  1. Registre cada 131026 com contato, data e template.
  2. Depois de falhas repetidas em datas diferentes, marque o contato como whatsapp_indisponivel e tire-o das campanhas.
  3. Peça atualização do número por e-mail ou na próxima interação no seu site ou app.
  4. Reative o contato automaticamente se ele mandar mensagem para você.
  5. Acompanhe a taxa de 131026 por origem do lead (formulário, importação, loja física). Uma origem com taxa alta indica problema de captura.

O artigo sobre lista opt-in para WhatsApp mostra como capturar o número com confirmação, o que reduz o primeiro tipo de falha.

Exemplo de código: classificar e marcar o contato

O trecho abaixo trata o status do webhook, separa o 131026 e decide entre fallback e marcação do contato. O limite de falhas é uma escolha sua, não da Meta.

const LIMITE_FALHAS = 3; // falhas 131026 em dias diferentes antes de suspender

async function onStatus(status, db, fallback) {
  if (status.status !== 'failed') return;
  const err = (status.errors || []).find(e => e.code === 131026);
  if (!err) return;

  const contato = await db.contatos.findByWaId(status.recipient_id);
  const msg = await db.mensagens.findByWamid(status.id);

  await db.falhas.insert({
    wa_id: status.recipient_id,
    wamid: status.id,
    code: err.code,
    details: err.error_data?.details,
    dia: new Date(Number(status.timestamp) * 1000).toISOString().slice(0, 10)
  });

  // Mensagem transacional: avisar por outro canal
  if (msg?.tipo === 'transacional' && contato?.email) {
    await fallback.email(contato.email, msg.resumo);
  }

  // Sem nenhuma conversa anterior e falhas repetidas: suspender o contato
  const dias = await db.falhas.distinctDias(status.recipient_id, 131026);
  if (!contato?.ultima_mensagem_recebida && dias.length >= LIMITE_FALHAS) {
    await db.contatos.update(status.recipient_id, { whatsapp_indisponivel: true });
  }
}

Quando chegar uma mensagem do contato (messages no webhook), zere o marcador: o WhatsApp dele voltou a funcionar.

Como fazer isso com a Vectalk

A Vectalk é um proxy da Cloud API oficial da Meta, então o 131026 chega igual: status failed no webhook, com o mesmo array errors da documentação da Meta. O código acima funciona sem mudança. Para revisar as falhas de um período, use GET https://apis.vectalk.com.br/api/messages?status=failed&from=2026-10-01, descrito em Listar Mensagens.

Na Vectalk, cada mensagem entregue é descontada do saldo pré-pago, e a Vectalk paga a Meta. Uma mensagem que falha com 131026 não foi entregue. Crie sua conta em apps.vectalk.com.br/register e veja o panorama no guia da API oficial do WhatsApp.

Perguntas frequentes

O erro 131026 significa que o número não tem WhatsApp?

Pode significar, mas não só isso. A Meta lista três causas: número sem WhatsApp, termos e política de privacidade não aceitos, e versão antiga do aplicativo. O código é o mesmo para as três.

O erro 131026 quer dizer que o cliente me bloqueou?

A tabela de erros não lista bloqueio como causa do 131026. O bloqueio aparece na página de suporte da Meta entre os motivos para mensagens que ficam como enviadas sem entrega, e a Meta avisa que muitas vezes não revela a causa.

Sou cobrado por mensagens com erro 131026?

Não. A Meta só cobra mensagens entregues, e uma mensagem com status failed não foi entregue.

Quantas vezes devo reenviar?

Nenhuma de imediato. Peça ao contato, por outro canal, que confirme o número, atualize o app e aceite os termos. Volte a enviar quando ele confirmar ou mandar mensagem para você.

Posso evitar o 131026 antes de enviar?

Dá para reduzir. Capture o número com confirmação, normalize o formato internacional e priorize contatos que já conversaram com você. Para quem nunca falou com a empresa, não há como garantir a entrega antes do envio.

Fontes oficiais consultadas em 29/10/2026: Códigos de erro da WhatsApp Cloud API, Suporte da WhatsApp Cloud API, Referência do webhook de status, Preços da plataforma do WhatsApp Business, Listar Mensagens na documentação da Vectalk.

Teste a API oficial do WhatsApp hoje

Crie sua conta, gere o token e envie a primeira mensagem seguindo o guia da documentação. Mesmos payloads e webhooks da Cloud API da Meta.

Criar conta grátis
Ler a documentação