Saltar para o conteúdo principal

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.

​
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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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 StatusAçãoEstratégia de Retry
400, 404, 422❌ Não faça retryCorrija a requisição e tente novamente
401, 403❌ Não faça retryAtualize a autenticação
429⏰ Retry com backoffUse o header retry_after
500, 502, 503🔄 Retry com backoff exponencialMáximo de 3 tentativas

​
Exemplo de Implementação

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.