Erros

Todas as respostas de erro seguem um formato consistente. Quando uma requisição falha, a API retorna um objeto JSON com o campo error contendo a mensagem descritiva.

Códigos HTTP

Código	Nome	Descrição
400	Bad Request	O body da requisição é inválido ou faltam campos obrigatórios
401	Unauthorized	API key ausente ou inválida
403	Forbidden	A API key não tem permissão para este recurso
404	Not Found	O recurso solicitado não existe
429	Too Many Requests	Limite de requisições excedido
500	Internal Server Error	Erro inesperado no servidor
502	Bad Gateway	O engine da sessão está inacessível ou não responde

Formato do Erro

{
  "error": "Session not found"
}

O campo error sempre contém uma string legível em inglês descrevendo o problema.

Rate Limiting

A API retorna headers de rate limit em todas as respostas:

Header	Descrição
X-RateLimit-Limit	Número máximo de requisições permitidas na janela
X-RateLimit-Remaining	Requisições restantes na janela atual

Quando você recebe 429 Too Many Requests:

1. Pare de enviar requisições imediatamente
2. Leia o header Retry-After (segundos até a janela resetar)
3. Aguarde o tempo indicado antes de tentar novamente
4. Implemente exponential backoff para retries subsequentes

Erros Comuns

Erro	Causa	Solução
Unauthorized	Header x-api-key ausente ou valor incorreto	Verifique se o header está presente e a key é válida
Session not found	O sessionId não existe ou foi removido	Liste as sessões ativas em GET /sessions
Engine unavailable	O container da sessão está offline ou reiniciando	Aguarde alguns segundos e tente novamente
Session not connected	A sessão existe mas o WhatsApp não está pareado	Inicie o pairing via QR code ou phone number
Invalid phone number	O número enviado não é um JID válido	Use formato internacional sem +: 5511999999999
Rate limit exceeded	Muitas requisições em curto período	Reduza a frequência e implemente backoff
Request body invalid	JSON malformado ou campos com tipo incorreto	Valide o body contra a documentação do endpoint