Erro 463: primeiro contato bloqueado e número restrito

O envio responde 200 com o messageId, e segundos depois chega o webhook message.failed. Na maioria dos casos o motivo é o erro 463 do WhatsApp. Este guia explica o que ele significa, como saber qual das duas causas é a sua e o que fazer em cada uma.

O que é

O WhatsApp exige um token de privacidade para uma mensagem 1:1 chegar a quem ainda não tem conversa com o seu número. Sem o token, o servidor recusa a mensagem com o código 463, depois de já ter aceitado o envio. Por isso a API responde 200 e a falha só aparece no webhook.

O mesmo código tem duas causas, e o errorCode do message.failed diz qual foi:

`errorCode`	O que aconteceu	Quem é afetado
`FIRST_CONTACT_BLOCKED`	O contato nunca conversou com o número e o WhatsApp não liberou o primeiro contato	Só aquele contato
`ACCOUNT_RESTRICTED`	O WhatsApp restringiu o número para iniciar conversas novas por um tempo	Todo contato novo, até a restrição acabar

Conversas que já existem continuam funcionando nos dois casos: quem já trocou mensagens com o número segue recebendo.

Para separar as duas causas, depois de um 463 o DevZap consulta no WhatsApp se o número está restrito (no máximo uma consulta por minuto por instância). Se a consulta não responder, vale FIRST_CONTACT_BLOCKED: só afirmamos restrição quando o WhatsApp confirma.

Como chega no webhook

{
  "event": "message.failed",
  "instanceId": "INST-A1B2C3",
  "timestamp": "2026-09-27T14:30:05.000Z",
  "data": {
    "instanceId": "INST-A1B2C3",
    "messageId": "true_5511123456789@c.us_3EB0...",
    "externalId": "true_5511123456789@c.us_3EB0...",
    "internalId": 4217,
    "status": "failed",
    "failedAt": "2026-09-27T14:30:05.000Z",
    "errorCode": "FIRST_CONTACT_BLOCKED",
    "providerCode": "463",
    "reason": "O WhatsApp recusou a mensagem porque este número ainda não tem conversa com o contato (erro 463). Não reenvie."
  }
}

Decida pelo errorCode, que é estável. reason é para mostrar a uma pessoa e o texto pode mudar. providerCode é o código cru do WhatsApp, útil para abrir chamado. Falhas com outro código chegam como DELIVERY_FAILED. O mesmo motivo fica gravado no histórico da mensagem.

Não reenvie

Nunca reenvie automaticamente uma mensagem que falhou com 463. Para o WhatsApp, cada nova tentativa é mais um contato novo, e insistir é exatamente o comportamento que leva à restrição do número (ou a prolonga). O DevZap também não reenvia: nem a fila nem os agendamentos tentam de novo uma mensagem que o WhatsApp recusou depois do envio.

Marque a mensagem para tratamento humano e siga as recomendações abaixo.

O que fazer

Peça para o contato mandar a primeira mensagem. É o caminho mais seguro: com a conversa aberta pelo contato, as próximas mensagens do seu número chegam normalmente. Um link https://wa.me/55DDDNUMERO no seu site, e-mail ou boleto resolve isso sem atrito.

Peça para o contato salvar o seu número. Contato que tem o número na agenda recebe com muito mais facilidade.

Use um número antigo e aquecido. Número recém-criado, ou que ficou parado por muito tempo e volta disparando para muita gente, é o perfil que mais recebe 463. Um número que já conversa normalmente com clientes há meses sofre muito menos.

Mande para poucos contatos novos por hora. Espalhe os primeiros contatos ao longo do dia. Rajadas de mensagens para quem nunca falou com o número são o gatilho mais comum de restrição.

Evite a cobrança seca como primeira mensagem. Uma primeira mensagem só com valor e link de pagamento, para quem não esperava, tende a ser denunciada e piora a situação do número. Prefira se apresentar, dizer de onde vem o contato e dar uma forma fácil de responder.

Se veio ACCOUNT_RESTRICTED, pare os primeiros contatos até a restrição acabar. Continue atendendo quem já conversa com o número.

Como ler os limites do número

GET /api/v1/instances/{instanceId}/limits mostra o que o WhatsApp informou sobre o número:

{
  "success": true,
  "data": {
    "instanceId": "INST-A1B2C3",
    "connected": true,
    "restricted": true,
    "restrictionEndsAt": "2026-09-28T15:00:00.000Z",
    "enforcementType": "BIZ_QUALITY",
    "newChatMessageCap": {
      "totalQuota": 50,
      "usedQuota": 50,
      "cycleStartsAt": "2026-09-27T00:00:00.000Z",
      "cycleEndsAt": "2026-10-04T00:00:00.000Z",
      "cappingStatus": "CAPPED"
    },
    "checkedAt": "2026-09-27T15:00:00.000Z"
  }
}

restricted: true enquanto o número não pode iniciar conversas novas. restrictionEndsAt traz o fim previsto, quando o WhatsApp informa.
enforcementType: o tipo de restrição que o WhatsApp informou. É uma lista aberta; use só para registro.
newChatMessageCap: o teto de mensagens para conversas novas no ciclo, quando o WhatsApp informa. cappingStatus vai de NONE a FIRST_WARNING, SECOND_WARNING e CAPPED; nos avisos, reduza o ritmo de primeiros contatos antes de chegar ao teto.
checkedAt: quando o DevZap recebeu essas informações. null significa que o WhatsApp ainda não disse nada sobre o número.

Com a instância conectada, a rota consulta o WhatsApp antes de responder, no máximo uma vez por minuto por instância; chamadas mais frequentes devolvem o último estado conhecido. Consultar antes de uma campanha de primeiros contatos é uma boa prática. Desconectada, vem o último estado conhecido com connected: false.

No painel, a instância restrita mostra o aviso "WhatsApp restringiu este número" no card da tela Instâncias.

← Todos os guias