Erros

Toda resposta de erro tem o mesmo corpo. code é estável e feito para o seu código tratar; message é para humanos e pode mudar.

{
  "error": {
    "code": "instance_not_connected",
    "message": "Instance is not connected",
    "details": {}
  }
}

details é opcional (em invalid_request traz issues com o caminho de cada campo inválido).

Códigos HTTP

HTTP	Quando
`400`	Body ou parâmetro inválido (`invalid_request`, `invalid_phone`)
`401`	Instância/token errados ou `Client-Token` ausente
`402`	Período de teste vencido ou assinatura inativa (só em endpoints de envio)
`403`	IP fora da allowlist do workspace
`404`	Recurso não encontrado (chat, grupo, produto, etiqueta…)
`409`	Estado incompatível: instância desconectada, fila cheia, fila desligada
`429`	Limite de requisições da instância
`5xx`	Falha interna ou engine indisponível — tente de novo com backoff

Códigos de erro

Autenticação e acesso

`code`	HTTP	Significado
`unauthorized`	401	Faltou `instance_id` ou `token` na URL
`instance_not_found`	401	Instância não existe ou token não confere (404 quando o erro vem de uma ação imediata)
`client_token_required`	401	Workspace exige o header `Client-Token` e ele está ausente ou errado
`ip_not_allowed`	403	IP de origem fora da allowlist
`subscription_required`	402	Teste vencido ou assinatura inativa; assine no painel
`rate_limited`	429	Veja `Retry-After` e Rate limit

Request e estado da instância

`code`	HTTP	Significado
`invalid_request`	400	Validação do body/query falhou (`details.issues`)
`invalid_phone`	400	`phone` fora do formato aceito
`not_found`	404	Recurso genérico não encontrado (ex.: QR code indisponível)
`instance_not_connected`	409	Ação imediata com a instância fora do ar
`instance_starting`	409	Sessão ainda carregando; tente em alguns segundos
`instance_already_connected`	409	Pareamento pedido com o número já conectado
`queue_full`	409	Mais de 1.000 mensagens aguardando nesta instância
`queue_disabled_while_disconnected`	409	`disable_enqueue_when_disconnected` ligado e instância desconectada
`engine_unavailable`	503	O nó que hospeda a instância não respondeu
`internal`	500	Erro inesperado

Erros de operação (ações imediatas ou webhook `delivery`)

Estes aparecem como resposta HTTP nas ações imediatas e em error_code no webhook delivery quando um envio falha.

`code`	HTTP (ação imediata)	Significado
`phone_not_on_whatsapp`	404	O número não tem WhatsApp
`send_failed`	502	O WhatsApp recusou o envio
`send_timeout`	504	O aparelho não confirmou o envio a tempo
`not_allowed`	403	A conta não pode executar a ação (ex.: enviar para quem te bloqueou, admin necessário)
`shadow_ban`	403	O WhatsApp aceitou o envio mas as mensagens não estão chegando; pare os envios e veja Boas práticas
`group_suspended`	403	Grupo suspenso pelo WhatsApp
`media_download_failed`	422	O engine não conseguiu baixar a URL de mídia informada
`media_invalid`	400	Mídia acima do limite ou em formato não aceito
`message_not_found`	404	A mensagem referenciada (responder, encaminhar, editar, votar) não está no cache do engine — veja Fila e reenvio
`group_not_found` / `chat_not_found` / `newsletter_not_found`	404	Id inválido ou a conta não participa
`invite_link_invalid`	400	Link de convite inválido ou revogado
`product_not_found` / `order_not_found` / `label_not_found`	404	Recurso de catálogo/etiqueta inexistente
`action_failed`	502	O aparelho respondeu com erro genérico; repetir costuma resolver

Como tratar

429: espere Retry-After segundos. O limite é por instância; distribua envios em várias instâncias se precisar de mais.
409 instance_not_connected: consulte GET /status; se status for qr ou logged_out, o número precisa ler o QR de novo. Envios enfileirados não sofrem disso.
402: leitura e webhooks continuam funcionando; só os envios param até a assinatura.
5xx e timeouts de rede: repita com backoff exponencial. Envios são seguros de repetir? Não automaticamente — se a primeira chamada chegou, você mandaria duas mensagens. Guarde o wabox_id da resposta antes de repetir e confirme pelo webhook delivery ou por GET /queue.

Introdução

Endpoints

Webhooks

Instância

Mensagens

Fila

Contatos

Perfil

Grupos

Chats

Interativos

Privacidade

Comunidades

Canais

Business e catálogo

Etiquetas

Partner

Webhooks

Códigos HTTP

Códigos de erro

Autenticação e acesso

Request e estado da instância

Erros de operação (ações imediatas ou webhook `delivery`)

Como tratar

​Códigos HTTP

​Códigos de erro

​Autenticação e acesso

​Request e estado da instância

​Erros de operação (ações imediatas ou webhook delivery)

​Como tratar

Códigos HTTP

Códigos de erro

Autenticação e acesso

Request e estado da instância

Erros de operação (ações imediatas ou webhook `delivery`)

Como tratar