Erros e códigos HTTP

Toda resposta de erro usa o mesmo envelope. O campo error.code (em snake_case) é estável, programe contra ele, não contra a mensagem.

Envelope

{
  "error": {
    "code": "instance_not_connected",
    "message": "Instância não está conectada ao WhatsApp. Conecte via QR Code e tente de novo.",
    "details": { "instanceId": "ins_abc123" },
    "requestId": "req_abc123"
  }
}

Guarde o requestId nos seus logs, ele agiliza o suporte.

Códigos HTTP

Código	Uso
`400`	Erro de validação no input
`401`	Token inválido ou ausente
`403`	Sem permissão para o recurso
`404`	Recurso não encontrado
`409`	Conflito de estado
`422`	Validação semântica falhou
`429`	Rate limit excedido
`500`	Erro inesperado do servidor
`502`	O WhatsApp falhou ao completar a operação

Códigos de erro comuns

`error.code`	Significado
`invalid_token` · `missing_token` · `expired_token`	Problemas de autenticação
`invalid_request` · `invalid_phone_number` · `invalid_media_url` · `message_too_long`	Validação de entrada
`instance_not_found` · `instance_not_connected` · `instance_limit_reached`	Estado da instância
`rate_limit_exceeded` · `quota_exceeded`	Limites
`trial_expired` · `subscription_inactive`	Assinatura
`number_not_on_whatsapp` · `whatsapp_disconnected` · `qr_code_expired`	WhatsApp