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

# Tratamento de Erros e Códigos de Resposta

> Guia abrangente para tratamento de erros e códigos de resposta da API

## Introdução

Este guia abrange todos os possíveis códigos de resposta, formatos de erro e boas práticas para tratamento de erros ao integrar com a API da Lovi.

## 📊 Códigos de Status HTTP

### Respostas de Sucesso

#### 200 OK - Requisição Bem-sucedida

**Notificação Processada:**

```json theme={null}
{
  "success": true,
  "message": "Notification queued successfully",
  "notification_id": "uuid-notification-123",
  "scheduled_time": "2024-12-25T10:30:00Z"
}
```

***

### Respostas de Erro do Cliente (4xx)

#### 400 Bad Request - Parâmetros Inválidos

**Campo Obrigatório Ausente:**

```json theme={null}
{
  "error": "validation_failed",
  "message": "Required field missing",
  "details": {
    "field": "contact.number",
    "reason": "This field is required"
  },
  "request_id": "req_123456789"
}
```

#### 401 Unauthorized - Autenticação Falhou

**Chave de Acesso Inválida:**

```json theme={null}
{
  "error": "unauthorized",
  "message": "Invalid or expired access key",
  "details": {
    "reason": "The provided access_key is not valid or has been revoked"
  },
  "request_id": "req_123456793"
}
```

#### 403 Forbidden - Acesso Negado

**Permissões Insuficientes:**

```json theme={null}
{
  "error": "forbidden",
  "message": "Insufficient permissions for this resource",
  "details": {
    "reason": "Your API key does not have permission to create templates"
  },
  "request_id": "req_123456795"
}
```

#### 404 Not Found - Recurso Não Encontrado

**Template Não Encontrado:**

```json theme={null}
{
  "error": "template_not_found",
  "message": "Template 'welcome_user' not found or not approved",
  "details": {
    "template_name": "welcome_user",
    "language": "es_ES",
    "suggestion": "Check template name and approval status"
  },
  "request_id": "req_123456797"
}
```

#### 422 Unprocessable Entity - Erro de Lógica de Negócio

#### 429 Too Many Requests - Limite de Taxa Excedido

**Limite de Taxa Atingido:**

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again in 60 seconds",
  "details": {
    "limit": 100,
    "window": "1 hour",
    "reset_time": "2024-12-20T16:30:00Z"
  },
  "retry_after": 60,
  "request_id": "req_123456801"
}
```

***

### Respostas de Erro do Servidor (5xx)

#### 500 Internal Server Error

#### 502 Bad Gateway

#### 503 Service Unavailable

***

## 🔄 Estratégias de Retry

### Lógica de Retry Recomendada

| Código de Status | Ação                                 | Estratégia de Retry                    |
| ---------------- | ------------------------------------ | -------------------------------------- |
| `400, 404, 422`  | ❌ **Não faça retry**                 | Corrija a requisição e tente novamente |
| `401, 403`       | ❌ **Não faça retry**                 | Atualize a autenticação                |
| `429`            | ⏰ **Retry com backoff**              | Use o header `retry_after`             |
| `500, 502, 503`  | 🔄 **Retry com backoff exponencial** | Máximo de 3 tentativas                 |

### Exemplo de Implementação

```javascript theme={null}
async function makeAPIRequest(url, data, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data)
      });

      const result = await response.json();

      if (response.ok) {
        return result;
      }

      if (response.status === 429) {
        const retryAfter = result.retry_after || 60;
        await sleep(retryAfter * 1000);
        continue;
      }

      if ([500, 502, 503].includes(response.status)) {
        if (attempt < maxRetries) {
          await sleep(Math.pow(2, attempt) * 1000);
          continue;
        }
      }

      throw new APIError(result.error, result.message, response.status);

    } catch (error) {
      if (attempt === maxRetries) throw error;
      await sleep(Math.pow(2, attempt) * 1000);
    }
  }
}
```

***

## 📝 Boas Práticas

### Checklist de Tratamento de Erros

✅ **Validação Pré-requisição**

* Valide formato do número de telefone
* Verifique campos obrigatórios
* Valide formato de datetime
* Verifique se o template existe

✅ **Monitoramento de Requisições**

* Registre todas as requisições de API
* Inclua request\_id nos logs
* Monitore tempos de resposta
* Acompanhe taxas de erro

✅ **Recuperação de Erros**

* Implemente lógica de retry apropriada
* Cache tokens de autenticação
* Trate limites de taxa graciosamente
* Forneça mensagens de erro significativas aos usuários

✅ **Experiência do Usuário**

* Mostre mensagens de erro amigáveis
* Forneça feedback acionável
* Não exponha detalhes internos de erro
* Ofereça alternativas quando possível

### Monitoramento e Alertas

**Métricas-chave para Monitorar:**

* Taxa de erro por endpoint
* Tempo médio de resposta
* Atingimentos de limite de taxa
* Falhas de autenticação
* Erros de template não encontrado

**Limites de Alerta:**

* Taxa de erro > 5%
* Tempo de resposta > 2 segundos
* Atingimentos de limite de taxa > 10/hora
* Falhas de autenticação > 20/hora

***

## 🚨 Problemas Comuns e Soluções

### Problemas de Autenticação

**Problema**: `Invalid or expired access key`
**Solução**:

1. Verifique se access\_key está nos parâmetros da URL
2. Confirme que a chave não foi revogada
3. Certifique-se de usar a chave da empresa correta

### Problemas de Template

**Problema**: `Template not found`
**Soluções**:

1. Verifique a ortografia do nome do template
2. Confirme que o idioma do template corresponde
3. Certifique-se de que o template está aprovado
4. Use GET /templates para listar templates disponíveis

### Limitação de Taxa

**Problema**: `Too many requests`
**Soluções**:

1. Implemente backoff exponencial
2. Respeite headers retry\_after
3. Agrupe requisições quando possível
4. Monitore padrões de uso

### Validação de Dados

**Problema**: `Validation failed`
**Soluções**:

1. Valide dados antes de enviar
2. Use formato adequado de número de telefone
3. Verifique formato de datetime
4. Confirme que campos obrigatórios estão presentes

Lembre-se de sempre incluir o `request_id` ao contatar o suporte para resolução mais rápida de problemas.