Skip to main content

​
Introducción

Esta guía cubre todos los posibles códigos de respuesta, formatos de error y mejores prácticas para manejar errores al integrar con la API de Lovi.

​
📊 Códigos de Estado HTTP

​
Respuestas Exitosas

​
200 OK - Solicitud Exitosa

Notificación Procesada: 
{
  "success": true,
  "message": "Notificación puesta en cola correctamente",
  "notification_id": "uuid-notificacion-123",
  "scheduled_time": "2024-12-25T10:30:00Z"
}
Plantillas Recuperadas: 
{
  "templates": [
    {
      "id": "template_001",
      "name": "welcome_user",
      "status": "approved"
    }
  ],
  "total": 1
}
Plantilla Creada: 
{
  "success": true,
  "message": "Plantilla creada correctamente",
  "template": {
    "id": "new_template_123",
    "name": "order_confirmation",
    "status": "pending"
  }
}

​
Respuestas de Error del Cliente (4xx)

​
400 Bad Request - Parámetros Inválidos

Campo Requerido Faltante: 
{
  "error": "validation_failed",
  "message": "Campo requerido faltante",
  "details": {
    "field": "contact.number",
    "reason": "Este campo es requerido"
  },
  "request_id": "req_123456789"
}
Formato de Parámetro Inválido: 
{
  "error": "validation_failed",
  "message": "Formato de parámetro inválido",
  "details": {
    "field": "datetime_sending",
    "provided": "25-12-2024",
    "expected_format": "ISO 8601 (YYYY-MM-DDTHH:MM:SS)",
    "example": "2024-12-25T10:30:00"
  },
  "request_id": "req_123456790"
}
Número de Teléfono Inválido: 
{
  "error": "validation_failed",
  "message": "Formato de número de teléfono inválido",
  "details": {
    "field": "contact.number",
    "provided": "+34-666-033-135",
    "expected_format": "Solo números, sin + ni espacios",
    "example": "34666033135"
  },
  "request_id": "req_123456791"
}
Hora Programada en el Pasado: 
{
  "error": "validation_failed",
  "message": "La hora programada debe ser en el futuro",
  "details": {
    "field": "datetime_sending",
    "provided": "2024-12-20T10:00:00",
    "current_time": "2024-12-20T15:30:00Z"
  },
  "request_id": "req_123456792"
}

​
401 Unauthorized - Autenticación Fallida

Clave de Acceso Inválida: 
{
  "error": "unauthorized",
  "message": "Clave de acceso inválida o expirada",
  "details": {
    "reason": "La access_key proporcionada no es válida o ha sido revocada"
  },
  "request_id": "req_123456793"
}
Clave de Acceso Faltante: 
{
  "error": "unauthorized",
  "message": "Clave de acceso faltante",
  "details": {
    "reason": "El parámetro access_key es requerido en la URL"
  },
  "request_id": "req_123456794"
}

​
403 Forbidden - Acceso Denegado

Permisos Insuficientes: 
{
  "error": "forbidden",
  "message": "Permisos insuficientes para este recurso",
  "details": {
    "reason": "Tu clave API no tiene permiso para crear plantillas"
  },
  "request_id": "req_123456795"
}

​
404 Not Found - Recurso No Encontrado

Plantilla No Encontrada: 
{
  "error": "template_not_found",
  "message": "Plantilla 'welcome_user' no encontrada o no aprobada",
  "details": {
    "template_name": "welcome_user",
    "language": "es_ES",
    "suggestion": "Verifica el nombre de la plantilla y su estado de aprobación"
  },
  "request_id": "req_123456797"
}

​
422 Unprocessable Entity - Error de Lógica de Negocio

Plantilla No Aprobada: 
{
  "error": "template_not_approved",
  "message": "La plantilla no está en estado aprobado",
  "details": {
    "template_name": "pending_template",
    "current_status": "pending",
    "required_status": "approved"
  },
  "request_id": "req_123456799"
}

​
429 Too Many Requests - Límite de Tasa Excedido

Límite de Tasa Alcanzado: 
{
  "error": "rate_limit_exceeded",
  "message": "Demasiadas solicitudes. Inténtalo de nuevo en 60 segundos",
  "details": {
    "limit": 100,
    "window": "1 hora",
    "reset_time": "2024-12-20T16:30:00Z"
  },
  "retry_after": 60,
  "request_id": "req_123456801"
}

​
Respuestas de Error del Servidor (5xx)

​
500 Internal Server Error

{
  "error": "internal_error",
  "message": "Ocurrió un error inesperado",
  "details": {
    "reason": "Error interno del servidor"
  },
  "request_id": "req_123456803"
}

​
503 Service Unavailable

{
  "error": "service_unavailable",
  "message": "Servicio temporalmente no disponible por mantenimiento",
  "details": {
    "maintenance_window": "2024-12-20T02:00:00Z to 2024-12-20T04:00:00Z"
  },
  "request_id": "req_123456805"
}

​
🔄 Estrategias de Reintento

​
Lógica de Reintento Recomendada

Código de EstadoAcciónEstrategia de Reintento
400, 404, 422❌ No reintentarCorregir la solicitud e intentar de nuevo
401, 403❌ No reintentarActualizar la autenticación
429⏰ Reintentar con esperaUsar el encabezado retry_after
500, 502, 503🔄 Reintentar con backoff exponencialMáximo 3 intentos

​
Ejemplo de Implementación

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);
    }
  }
}

​
📝 Mejores Prácticas

​
Lista de Verificación para el Manejo de Errores

✅ Validación Previa a la Solicitud
  • Validar formato del número de teléfono
  • Verificar campos requeridos
  • Validar formato de fecha y hora
  • Verificar que la plantilla existe
✅ Monitorización de Solicitudes
  • Registrar todas las solicitudes a la API
  • Incluir request_id en los registros
  • Monitorizar tiempos de respuesta
  • Rastrear tasas de error
✅ Recuperación de Errores
  • Implementar lógica de reintento apropiada
  • Almacenar tokens de autenticación en caché
  • Manejar los límites de tasa con elegancia
  • Proporcionar mensajes de error significativos a los usuarios

​
Métricas Clave a Monitorizar

  • Tasa de error por endpoint
  • Tiempo de respuesta promedio
  • Alcances del límite de tasa
  • Fallos de autenticación
  • Errores de plantilla no encontrada
Recuerda incluir siempre el request_id al contactar con soporte para una resolución más rápida de los problemas.