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 API key ausente ou inválida
`402`	Período de teste vencido ou assinatura inativa (só em endpoints de envio)
`403`	IP fora da allowlist do workspace, API key sem a permissão da rota, conta em trial na Account API
`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)
`api_key_required`	401	API key ausente ou inválida (revogada, inexistente ou de outro workspace). Nas rotas de instância, só quando o workspace exige uma key; na Account API, sempre
`insufficient_scope`	403	A API key é válida mas não tem a permissão da rota; `details.required_scope` diz qual falta
`ip_not_allowed`	403	IP de origem fora da allowlist
`subscription_required`	402	Teste vencido ou plano da conta inativo; assine no painel
`plan_required`	403	Account API: conta em trial; criar instâncias por API exige um plano
`instance_limit_reached`	409	Account API: todos os slots do plano em uso; exclua uma instância ou aumente o plano
`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`	429	Mais de 1.000 mensagens aguardando nesta instância
`queue_disabled_while_disconnected`	409	`disable_enqueue_when_disconnected` ligado e instância desconectada
`duplicate_message_id`	409	`custom_message_id` já usado por uma mensagem na fila ou enviada desta instância (`details.wabox_id` = envio existente)
`engine_unavailable`	503	O nó que hospeda a instância não respondeu
`history_not_configured`	503	O ambiente não tem storage de histórico (`GET /chats/{phone}/messages`)
`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
`queue_expired`	Só no `delivery`	A mensagem passou de `queue_max_age_hours` na fila sem a instância enviar e foi descartada; reenviar é seguro

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. Repetir um envio não é seguro automaticamente. Se a primeira chamada chegou, você manda 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

Conta

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