Erros e códigos

A WS API segue convenções HTTP padrão. O body de erro é sempre um JSON com code (string), message (texto humano em PT-BR) e, opcionalmente, details.

Formato

{
  "code": "instance_not_connected",
  "message": "A instância está desconectada. Reconecte antes de enviar.",
  "details": {
    "state": "qr",
    "since": "2026-05-04T14:22:01Z"
  }
}

HTTP status

• 200 — sucesso.
• 400 Bad Request — body ou query string inválida.
• 401 Unauthorized — token ausente, malformado ou expirado.
• 403 Forbidden — token válido, mas não tem permissão pra essa instância.
• 404 Not Found — instância ou recurso inexistente.
• 409 Conflict — estado incompatível com a operação (ex.: enviar com instância desconectada).
• 422 Unprocessable Entity — dado válido em formato mas inválido em valor (ex.: telefone que não existe).
• 429 Too Many Requests — limite de fila atingido pra essa instância.
• 500 Internal Server Error — falha interna. Reporta pra gente, isso não devia acontecer.
• 503 Service Unavailable — manutenção ou degradação. Veja /status.

Códigos de aplicação

• invalid_phone — número fora do formato 55DDDxxxxxxxx.
• invalid_message — mensagem vazia ou maior que o limite.
• instance_not_found — instanceId não existe ou foi deletada.
• instance_not_connected — instância existe mas state !== "open".
• token_invalid — Bearer token incorreto.
• token_expired — token foi rotacionado e este é o antigo.
• rate_limited — você ou o WhatsApp atingiu um limite. Tente novamente mais tarde.

Tratamento recomendado

• 409 instance_not_connected → mostre o QR Code via /v1/instance/qrcode.
• 401 ou 403 → bloqueie a chamada e force regerar o token.
• 429 → backoff exponencial começando em 1s.
• 5xx → retry uma vez. Se persistir, alerte o operador.