Erro 131026 WhatsApp API: Mensagem Não Pode Ser Entregue

O que é o Erro 131026?

O erro 131026 indica que a mensagem não pode ser entregue ao destinatário. Este é um erro frustrante porque pode ter várias causas diferentes.

{
  "error": {
    "message": "(#131026) Message undeliverable",
    "type": "OAuthException",
    "code": 131026,
    "error_subcode": 2494010,
    "fbtrace_id": "..."
  }
}

Causas Comuns

1. Número não está no WhatsApp

O número do destinatário não está registrado no WhatsApp ou foi desativado.

Solução: Valide o número antes de enviar:

// Verificar se o número está no WhatsApp (não oficial, mas funcional)
async function checkWhatsAppNumber(phoneNumber) {
  try {
    const response = await fetch(
      `https://graph.facebook.com/v18.0/${phoneNumberId}/messages`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          messaging_product: 'whatsapp',
          to: phoneNumber,
          type: 'template',
          template: {
            name: 'hello_world',
            language: { code: 'pt_BR' }
          }
        })
      }
    );

    const data = await response.json();
    return !data.error;
  } catch (error) {
    return false;
  }
}

2. Usuário não aceitou os Termos de Serviço

O destinatário não aceitou a versão mais recente dos Termos de Serviço e Política de Privacidade do WhatsApp.

Solução: O usuário precisa abrir o WhatsApp e aceitar os novos termos.

3. Versão antiga do WhatsApp

O destinatário está usando uma versão muito antiga do WhatsApp que não suporta a API.

Solução: O usuário precisa atualizar o aplicativo WhatsApp.

4. Usuário bloqueou seu número

Se o usuário bloqueou seu número de negócio, as mensagens não serão entregues.

Solução: Não há solução técnica. Respeite a decisão do usuário.

5. Formato do número incorreto

O número está em formato incorreto.

Solução: Use o formato internacional sem símbolos:

function formatPhoneNumber(phone) {
  // Remove tudo que não for número
  let cleaned = phone.replace(/\D/g, '');

  // Remove o zero inicial se existir
  if (cleaned.startsWith('0')) {
    cleaned = cleaned.substring(1);
  }

  // Adiciona código do país se não tiver
  if (!cleaned.startsWith('55')) {
    cleaned = '55' + cleaned;
  }

  return cleaned;
}

// Exemplos:
// (11) 99999-9999 -> 5511999999999
// +55 11 99999-9999 -> 5511999999999
// 011 99999-9999 -> 5511999999999

Implementando Tratamento de Erro

async function sendWhatsAppMessage(to, message) {
  try {
    const response = await fetch(/* ... */);
    const data = await response.json();

    if (data.error) {
      switch (data.error.code) {
        case 131026:
          // Mensagem não pode ser entregue
          await handleUndeliverable(to, data.error);
          break;
        case 131047:
          // Janela de 24h expirada
          await sendTemplateInstead(to);
          break;
        default:
          throw new Error(data.error.message);
      }
    }

    return data;
  } catch (error) {
    console.error('Erro ao enviar mensagem:', error);
    throw error;
  }
}

async function handleUndeliverable(phoneNumber, error) {
  // Registre o número como inválido/problemático
  await markNumberAsInvalid(phoneNumber, {
    error_code: error.code,
    error_subcode: error.error_subcode,
    timestamp: new Date()
  });

  // Notifique sua equipe ou sistema
  await notifySupport({
    type: 'undeliverable_message',
    phone: phoneNumber,
    error: error
  });
}

Subcódigos de Erro

O erro 131026 pode vir com diferentes subcódigos:

| Subcódigo | Significado | |-----------|-------------| | 2494010 | Número não está no WhatsApp | | 2494011 | Termos de serviço não aceitos | | 2494012 | Versão do app muito antiga | | 2494013 | Conta desativada |

Boas Práticas

1. Valide números antes de enviar: Mantenha uma lista de números validados
2. Implemente retry com backoff: Alguns erros são temporários
3. Monitore taxa de falha: Muitos 131026 podem indicar problema na sua lista de contatos
4. Ofereça canais alternativos: Email, SMS como fallback

Exemplo de Retry com Backoff

async function sendWithRetry(to, message, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await sendWhatsAppMessage(to, message);
    } catch (error) {
      if (error.code === 131026 || attempt === maxRetries) {
        // Não faz retry para 131026 (não adianta)
        throw error;
      }

      // Backoff exponencial
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

Conclusão

O erro 131026 geralmente indica um problema com o número de destino, não com sua implementação. A melhor estratégia é validar números proativamente e ter fallbacks para quando mensagens não podem ser entregues.

Precisa de ajuda com sua integração WhatsApp? Fale comigo para consultoria especializada.