Skip to main content
Este guia reúne os problemas mais comuns em integrações via API Key e como resolver.

​
Checklist rápido

  • Confirme que você está usando a Base URL https://api.oxenty.api.br/api.
  • Envie sua API Key no header X-API-Key.
  • Para requisições com body, envie Content-Type: application/json.
  • Garanta que a sessão existe e está conectada antes de enviar mensagens.

​
401 — Não autenticado

Sintoma
  • Resposta 401 com erro UNAUTHORIZED.
Causas prováveis
  • Header X-API-Key ausente.
  • API Key inválida (copiada incompleta) ou revogada.
Como resolver
  • Confirme que o header está presente:
-H "X-API-Key: SUA_API_KEY"
  • Gere uma nova API Key no dashboard e teste novamente.

​
403 — Sem permissão

Sintoma
  • Resposta 403 com erro INSUFFICIENT_PERMISSIONS.
Causas prováveis
  • API Key não possui a permissão necessária para o endpoint.
Como resolver
  • Revise as permissões da API Key no dashboard e habilite apenas o necessário.
  • Se você estiver automatizando envio de mensagens, normalmente precisará de permissões como messages:send (quando aplicável).

​
404 — Recurso não encontrado

Sintoma
  • Resposta 404 (por exemplo, SESSION_NOT_FOUND).
Causas prováveis
  • sessionId incorreto.
  • Sessão foi deletada ou pertence a outro tenant.
Como resolver
  • Liste as sessões e valide o id.
  • Crie uma nova sessão e tente novamente.

​
409 — Conflito de estado

Sintoma
  • Resposta 409 (por exemplo, sessão com mesmo nome já existe).
Como resolver
  • Use um nome único ao criar sessões.
  • Em operações que dependem de estado, consulte a sessão (GET /sessions/:id) antes.

​
400/422 — Validação falhou

Sintoma
  • 400 VALIDATION_ERROR / 422 Unprocessable Entity.
Como resolver
  • Leia o campo message e, se existir, details no corpo do erro.
  • Confirme formatos comuns:
    • Telefone no padrão E.164 (ex.: 5511999999999).
    • JIDs quando exigidos (ex.: 5511999999999@s.whatsapp.net, ...@g.us).

​
429 — Rate limit excedido

Sintoma
  • Resposta 429 TOO_MANY_REQUESTS.
Como resolver
  • Reduza a taxa de requisições.
  • Implemente retry com backoff (ex.: 1s, 2s, 4s), respeitando o limite do seu plano.

​
500 — Erro interno

Como agir
  • Tente novamente após alguns segundos.
  • Se persistir, valide se a sessão está saudável (GET /sessions/:id) e revise seu payload.
  • Use o endpoint mais simples (ex.: enviar texto) para isolar o problema.
Para a lista completa de códigos e exemplos de payloads de erro, veja Tratamento de Erros.