> ## 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.

# Tratamento de Erros

> Como interpretar e tratar erros da Oxenty API

A Oxenty API usa códigos HTTP padrão para indicar sucesso ou falha das requisições. Erros incluem informações detalhadas para facilitar a depuração.

## Estrutura de Erro

Todas as respostas de erro seguem o mesmo formato:

```json theme={"system"}
{
  "statusCode": 400,
  "error": "VALIDATION_ERROR",
  "message": "O campo 'phone' é obrigatório",
  "details": {
    "field": "phone",
    "constraint": "required"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/messages/send"
}
```

| Campo        | Tipo   | Descrição                           |
| ------------ | ------ | ----------------------------------- |
| `statusCode` | number | Código HTTP do erro                 |
| `error`      | string | Código identificador do erro        |
| `message`    | string | Mensagem legível descrevendo o erro |
| `details`    | object | Informações adicionais (opcional)   |
| `timestamp`  | string | Data/hora do erro (ISO 8601)        |
| `path`       | string | Endpoint que gerou o erro           |

***

## Códigos HTTP

<Tabs>
  <Tab title="2xx Sucesso">
    | Código | Significado                                |
    | ------ | ------------------------------------------ |
    | 200    | OK - Requisição bem sucedida               |
    | 201    | Created - Recurso criado com sucesso       |
    | 204    | No Content - Sucesso sem corpo de resposta |
  </Tab>

  <Tab title="4xx Erro do Cliente">
    | Código | Significado                             |
    | ------ | --------------------------------------- |
    | 400    | Bad Request - Requisição inválida       |
    | 401    | Unauthorized - Autenticação necessária  |
    | 403    | Forbidden - Sem permissão               |
    | 404    | Not Found - Recurso não encontrado      |
    | 409    | Conflict - Conflito com estado atual    |
    | 422    | Unprocessable Entity - Validação falhou |
    | 429    | Too Many Requests - Rate limit excedido |
  </Tab>

  <Tab title="5xx Erro do Servidor">
    | Código | Significado                                |
    | ------ | ------------------------------------------ |
    | 500    | Internal Server Error - Erro interno       |
    | 502    | Bad Gateway - Erro no serviço upstream     |
    | 503    | Service Unavailable - Serviço indisponível |
    | 504    | Gateway Timeout - Timeout no serviço       |
  </Tab>
</Tabs>

***

## Códigos de Erro

### Autenticação

| Código                     | HTTP | Descrição                    |
| -------------------------- | ---- | ---------------------------- |
| `UNAUTHORIZED`             | 401  | API Key ausente ou inválida  |
| `API_KEY_REVOKED`          | 403  | API Key foi revogada         |
| `INSUFFICIENT_PERMISSIONS` | 403  | Sem permissão para o recurso |

### Validação

| Código                   | HTTP | Descrição                    |
| ------------------------ | ---- | ---------------------------- |
| `VALIDATION_ERROR`       | 400  | Dados de entrada inválidos   |
| `INVALID_PHONE_FORMAT`   | 400  | Formato de telefone inválido |
| `INVALID_JID_FORMAT`     | 400  | Formato de JID inválido      |
| `MISSING_REQUIRED_FIELD` | 400  | Campo obrigatório ausente    |

### Sessões

| Código                    | HTTP | Descrição                           |
| ------------------------- | ---- | ----------------------------------- |
| `SESSION_NOT_FOUND`       | 404  | Sessão não existe                   |
| `SESSION_ALREADY_EXISTS`  | 409  | Sessão com mesmo nome já existe     |
| `SESSION_NOT_CONNECTED`   | 400  | Sessão não está conectada           |
| `SESSION_LIMIT_REACHED`   | 403  | Limite de sessões do plano atingido |
| `SESSION_CREATION_FAILED` | 500  | Falha ao criar sessão               |

### Mensagens

| Código                      | HTTP | Descrição                             |
| --------------------------- | ---- | ------------------------------------- |
| `MESSAGE_SEND_FAILED`       | 500  | Falha ao enviar mensagem              |
| `MESSAGE_LIMIT_REACHED`     | 403  | Limite de mensagens do plano atingido |
| `RECIPIENT_NOT_ON_WHATSAPP` | 400  | Destinatário não usa WhatsApp         |
| `MEDIA_TOO_LARGE`           | 400  | Arquivo excede o limite de tamanho    |
| `UNSUPPORTED_MEDIA_TYPE`    | 400  | Tipo de mídia não suportado           |

### Grupos

| Código                       | HTTP | Descrição                     |
| ---------------------------- | ---- | ----------------------------- |
| `GROUP_NOT_FOUND`            | 404  | Grupo não existe              |
| `NOT_GROUP_ADMIN`            | 403  | Não é administrador do grupo  |
| `PARTICIPANT_ALREADY_EXISTS` | 409  | Participante já está no grupo |
| `PARTICIPANT_NOT_FOUND`      | 404  | Participante não encontrado   |

### Contatos

| Código                   | HTTP | Descrição                   |
| ------------------------ | ---- | --------------------------- |
| `CONTACT_NOT_FOUND`      | 404  | Contato não encontrado      |
| `NUMBER_NOT_ON_WHATSAPP` | 400  | Número não está no WhatsApp |

### Rate Limiting

| Código                | HTTP | Descrição              |
| --------------------- | ---- | ---------------------- |
| `TOO_MANY_REQUESTS`   | 429  | Rate limit excedido    |
| `WHATSAPP_RATE_LIMIT` | 429  | Rate limit do WhatsApp |

### Webhooks

| Código                    | HTTP | Descrição                    |
| ------------------------- | ---- | ---------------------------- |
| `WEBHOOK_NOT_FOUND`       | 404  | Webhook não encontrado       |
| `WEBHOOK_URL_UNREACHABLE` | 400  | URL do webhook não acessível |
| `WEBHOOK_LIMIT_REACHED`   | 403  | Limite de webhooks do plano  |

***

## Tratamento de Erros

### Exemplo em TypeScript

```typescript theme={"system"}
import { OxentyClient, OxentyError } from 'oxenty-sdk';

const client = new OxentyClient({
  baseUrl: 'https://api.oxenty.api.br',
  apiKey: process.env.OXENTY_API_KEY,
});

async function sendMessage() {
  try {
    const result = await client.messages.sendText(sessionId, {
      to: '5511999999999',
      text: 'Olá!',
    });
    return result;
  } catch (error) {
    if (error instanceof OxentyError) {
      switch (error.code) {
        case 'SESSION_NOT_CONNECTED':
          // Reconectar sessão
          await client.sessions.connect(sessionId);
          break;
          
        case 'RECIPIENT_NOT_ON_WHATSAPP':
          // Notificar usuário
          console.log('Destinatário não usa WhatsApp');
          break;
          
        case 'TOO_MANY_REQUESTS':
          // Aguardar e tentar novamente
          await sleep(error.retryAfter * 1000);
          return sendMessage();
          
        case 'MESSAGE_LIMIT_REACHED':
          // Upgrade de plano necessário
          console.log('Limite de mensagens atingido');
          break;
          
        default:
          console.error(`Erro: ${error.message}`);
      }
    }
    throw error;
  }
}
```

### Exemplo em Python

```python theme={"system"}
import os
import time
import requests

API_KEY = os.environ.get('OXENTY_API_KEY')
BASE_URL = 'https://api.oxenty.api.br'

def send_message():
    try:
    response = requests.post(
      f"{BASE_URL}/api/messages/send-text",
      headers={
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json',
      },
      json={
        'sessionId': session_id,
        'to': '5511999999999',
        'text': 'Olá!'
      },
      timeout=30,
    )

    if response.status_code == 429:
      time.sleep(2)
      return send_message()

    response.raise_for_status()
    return response.json()
  except requests.HTTPError as err:
    try:
      payload = err.response.json()
      print(f"Erro: {payload.get('error')} - {payload.get('message')}")
    except Exception:
      print(f"Erro HTTP: {err}")
    raise
```

***

## Boas Práticas

<AccordionGroup>
  <Accordion title="Sempre trate erros específicos" icon="code">
    Não use apenas `catch` genérico. Trate cada tipo de erro de forma adequada para melhor experiência do usuário.
  </Accordion>

  <Accordion title="Implemente retry com backoff" icon="refresh-cw">
    Para erros 5xx e 429, implemente retry automático com exponential backoff.
  </Accordion>

  <Accordion title="Log erros para debugging" icon="file-text">
    Salve logs detalhados de erros incluindo timestamp, path, e details para facilitar troubleshooting.
  </Accordion>

  <Accordion title="Monitore taxa de erros" icon="bell">
    Configure alertas quando a taxa de erros 4xx ou 5xx ultrapassar um threshold.
  </Accordion>
</AccordionGroup>

***

## Suporte

Se você encontrar um erro que não consegue resolver:

<CardGroup cols={2}>
  <Card title="Status Page" icon="signal" href="https://status.oxenty.api.br">
    Verifique o status dos serviços
  </Card>

  <Card title="WhatsApp" icon="phone" href="https://wa.me/558781148453">
    Suporte e atendimento: +55 87 8114-8453
  </Card>
</CardGroup>