> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oxenty.api.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Solução de problemas

> Erros comuns, causas prováveis e como resolver rapidamente

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:

```bash theme={"system"}
-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.

<Note>
  Para a lista completa de códigos e exemplos de payloads de erro, veja [Tratamento de Erros](/errors).
</Note>