Skip to main content
Toda resposta desta API — de sucesso ou de erro — vem dentro de um envelope. Escreva o seu cliente para ler o envelope, não o conteúdo direto.

​
Resposta de sucesso

O conteúdo útil está sempre em data. O conteúdo útil está sempre em data, em uma única camada.
Listas vêm em items. Quando o endpoint pagina, limit e offset acompanham items dentro de data.

​
Resposta de erro

O código legível por máquina fica em message.error. É por ele que o seu cliente deve decidir o que fazer — nunca pelo texto de message.message, que pode mudar.

​
O campo errorId

Todo erro carrega um errorId único. Ele é a referência que permite ao suporte localizar a requisição exata nos registros do servidor, inclusive nos casos em que a mensagem devolvida é genérica.
Guarde o errorId nos seus próprios registros. Ao abrir um chamado, envie-o junto: sem ele, um erro genérico é praticamente impossível de rastrear.

​
Códigos de erro

SEND_FAILED cobre mais do que falha de infraestrutura. Hoje ele também é devolvido quando o envio é recusado por regra de negócio — texto acima do limite de 4096 caracteres, número sem conversa anterior, conta de WhatsApp desconectada ou teto de envio por número atingido. Ao receber SEND_FAILED, trate como possível problema da requisição, não só como falha temporária.

​
Erros de limite de plano

O 403 de limite de plano não traz código nomeado, e a mensagem devolvida é genérica. Se a criação de contato passar a responder 403, verifique o consumo do plano no painel.

​
Erro de limite de requisições

O 429 também não traz código nomeado:
Repare que neste caso message é um texto, e não um objeto. Erros com código nomeado trazem message como objeto ({ "error": …, "message": … }); erros sem código nomeado, como o 429 e o 401, podem trazê-lo como texto. Trate os dois formatos ao ler o campo.
Os cabeçalhos da resposta dizem quanto esperar. Veja Limites de uso.

​
Erros vindos do WhatsApp

O envio é assíncrono: a API responde 201 assim que aceita a mensagem, antes de falar com o WhatsApp. Por isso, uma recusa do WhatsApp nunca aparece na resposta do envio. Ela aparece depois, no campo failed_reason da consulta de status, já traduzida para português. Veja Status da mensagem.