Passer au contenu 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.

​
Introduction

Ce guide couvre tous les codes de réponse possibles, les formats d’erreur et les bonnes pratiques pour la gestion des erreurs lors de l’intégration avec l’API Lovi.

​
📊 Codes de Statut HTTP

​
Réponses Réussies

​
200 OK - Requête Réussie

Notification Traitée : 
{
  "success": true,
  "message": "Notification queued successfully",
  "notification_id": "uuid-notification-123",
  "scheduled_time": "2024-12-25T10:30:00Z"
}
Templates Récupérés : 
{
  "templates": [
    {
      "id": "template_001",
      "name": "welcome_user",
      "status": "approved"
    }
  ],
  "total": 1
}
Template Créé : 
{
  "success": true,
  "message": "Template created successfully",
  "template": {
    "id": "new_template_123",
    "name": "order_confirmation",
    "status": "pending"
  }
}

​
Réponses d’Erreur Client (4xx)

​
400 Bad Request - Paramètres Invalides

Champ Requis Manquant : 
{
  "error": "validation_failed",
  "message": "Required field missing",
  "details": {
    "field": "contact.number",
    "reason": "This field is required"
  },
  "request_id": "req_123456789"
}
Format de Paramètre Invalide : 
{
  "error": "validation_failed",
  "message": "Invalid parameter format",
  "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"
}
Numéro de Téléphone Invalide : 
{
  "error": "validation_failed",
  "message": "Invalid phone number format",
  "details": {
    "field": "contact.number",
    "provided": "+34-666-033-135",
    "expected_format": "Numbers only, no + or spaces",
    "example": "34666033135"
  },
  "request_id": "req_123456791"
}
Heure Programmée dans le Passé : 
{
  "error": "validation_failed",
  "message": "Scheduled time must be in the future",
  "details": {
    "field": "datetime_sending",
    "provided": "2024-12-20T10:00:00",
    "current_time": "2024-12-20T15:30:00Z"
  },
  "request_id": "req_123456792"
}

​
401 Unauthorized - Échec d’Authentification

Clé d’Accès Invalide : 
{
  "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"
}
Clé d’Accès Manquante : 
{
  "error": "unauthorized",
  "message": "Missing access key",
  "details": {
    "reason": "access_key parameter is required in the URL"
  },
  "request_id": "req_123456794"
}

​
403 Forbidden - Accès Refusé

Permissions Insuffisantes : 
{
  "error": "forbidden",
  "message": "Insufficient permissions for this resource",
  "details": {
    "reason": "Your API key does not have permission to create templates"
  },
  "request_id": "req_123456795"
}
Accès à l’Entreprise Refusé : 
{
  "error": "forbidden",
  "message": "Access denied to company resources",
  "details": {
    "reason": "API key is not associated with the requested company"
  },
  "request_id": "req_123456796"
}

​
404 Not Found - Ressource Non Trouvée

Template Non Trouvé : 
{
  "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"
}
Agent Non Trouvé : 
{
  "error": "agent_not_found",
  "message": "Voice agent not found",
  "details": {
    "agent_id": "uuid-invalid-agent",
    "suggestion": "Verify agent_id exists and is active"
  },
  "request_id": "req_123456798"
}

​
422 Unprocessable Entity - Erreur de Logique Métier

Template Non Approuvé : 
{
  "error": "template_not_approved",
  "message": "Template is not in approved status",
  "details": {
    "template_name": "pending_template",
    "current_status": "pending",
    "required_status": "approved"
  },
  "request_id": "req_123456799"
}
Incohérence de Variables : 
{
  "error": "variable_mismatch",
  "message": "Template variables don't match provided data",
  "details": {
    "template_variables": ["name", "course"],
    "provided_variables": ["name", "email"],
    "missing": ["course"],
    "unexpected": ["email"]
  },
  "request_id": "req_123456800"
}

​
429 Too Many Requests - Limite de Requêtes Dépassée

Limite de Requêtes Atteinte : 
{
  "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"
}
Quota Journalier Dépassé : 
{
  "error": "quota_exceeded",
  "message": "Daily notification quota exceeded",
  "details": {
    "quota": 10000,
    "used": 10000,
    "reset_time": "2024-12-21T00:00:00Z"
  },
  "request_id": "req_123456802"
}

​
Réponses d’Erreur Serveur (5xx)

​
500 Internal Server Error

Erreur Serveur Générale : 
{
  "error": "internal_error",
  "message": "An unexpected error occurred",
  "details": {
    "reason": "Internal server error"
  },
  "request_id": "req_123456803"
}

​
502 Bad Gateway

Erreur de Service en Amont : 
{
  "error": "service_unavailable",
  "message": "WhatsApp service temporarily unavailable",
  "details": {
    "service": "whatsapp_gateway",
    "estimated_recovery": "2024-12-20T16:00:00Z"
  },
  "request_id": "req_123456804"
}

​
503 Service Unavailable

Mode Maintenance : 
{
  "error": "service_unavailable",
  "message": "Service temporarily unavailable for maintenance",
  "details": {
    "maintenance_window": "2024-12-20T02:00:00Z to 2024-12-20T04:00:00Z"
  },
  "request_id": "req_123456805"
}

​
🔄 Stratégies de Relance

​
Logique de Relance Recommandée

Code de StatutActionStratégie de Relance
400, 404, 422❌ Ne pas relancerCorrigez la requête et réessayez
401, 403❌ Ne pas relancerRafraîchissez l’authentification
429⏰ Relancer avec backoffUtilisez l’en-tête retry_after
500, 502, 503🔄 Relancer avec backoff exponentielMaximum 3 tentatives

​
Exemple d’Implémentation

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

      // Handle different error types
      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); // Exponential backoff
          continue;
        }
      }

      // Don't retry for 4xx errors (except 429)
      throw new APIError(result.error, result.message, response.status);

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

​
📝 Bonnes Pratiques

​
Journalisation des Erreurs

Enregistrez toujours ces champs : 
{
  "timestamp": "2024-12-20T15:30:00Z",
  "request_id": "req_123456789",
  "endpoint": "/notify",
  "method": "POST",
  "status_code": 400,
  "error_code": "validation_failed",
  "error_message": "Required field missing",
  "user_id": "user_123",
  "company_id": "company_456"
}

​
Liste de Contrôle pour la Gestion des Erreurs

✅ Validation Pré-requête
  • Validez le format du numéro de téléphone
  • Vérifiez les champs requis
  • Validez le format de la date et l’heure
  • Vérifiez que le template existe
✅ Surveillance des Requêtes
  • Enregistrez toutes les requêtes API
  • Incluez le request_id dans les logs
  • Surveillez les temps de réponse
  • Suivez les taux d’erreur
✅ Récupération après Erreur
  • Implémentez une logique de relance appropriée
  • Mettez en cache les tokens d’authentification
  • Gérez les limites de requêtes avec élégance
  • Fournissez des messages d’erreur significatifs aux utilisateurs
✅ Expérience Utilisateur
  • Affichez des messages d’erreur conviviaux
  • Fournissez des retours exploitables
  • N’exposez pas les détails d’erreur internes
  • Proposez des alternatives lorsque c’est possible

​
Surveillance et Alertes

Métriques Clés à Surveiller :
  • Taux d’erreur par endpoint
  • Temps de réponse moyen
  • Dépassements de limite de requêtes
  • Échecs d’authentification
  • Erreurs de template non trouvé
Seuils d’Alerte :
  • Taux d’erreur > 5%
  • Temps de réponse > 2 secondes
  • Dépassements de limite > 10/heure
  • Échecs d’authentification > 20/heure

​
🛠️ Outils de Développement

​
Tests d’Erreur

Testez différents scénarios d’erreur : 
# Missing access_key
curl -X POST https://cloud.lovi.ai/functions/v1/notify \
  -H "Content-Type: application/json" \
  -d '{"contact":{"number":"34666033135"}}'

# Invalid phone number
curl -X POST https://cloud.lovi.ai/functions/v1/notify?access_key=test \
  -H "Content-Type: application/json" \
  -d '{"contact":{"number":"+34-666-033-135"}}'

# Past datetime
curl -X POST https://cloud.lovi.ai/functions/v1/notify?access_key=test \
  -H "Content-Type: application/json" \
  -d '{"datetime_sending":"2020-01-01T10:00:00"}'

​
Analyseur de Réponses d’Erreur

class LoviAPIError extends Error {
  constructor(response) {
    super(response.message);
    this.name = 'LoviAPIError';
    this.code = response.error;
    this.statusCode = response.status;
    this.requestId = response.request_id;
    this.details = response.details;
  }

  isRetryable() {
    return [429, 500, 502, 503].includes(this.statusCode);
  }

  getRetryAfter() {
    return this.details?.retry_after || 60;
  }
}

​
🚨 Problèmes Courants et Solutions

​
Problèmes d’Authentification

Problème : Invalid or expired access key Solution :
  1. Vérifiez que l’access_key est dans les paramètres de l’URL
  2. Vérifiez que la clé n’a pas été révoquée
  3. Assurez-vous d’utiliser la bonne clé d’entreprise

​
Problèmes de Templates

Problème : Template not found Solutions :
  1. Vérifiez l’orthographe du nom du template
  2. Vérifiez que la langue du template correspond
  3. Assurez-vous que le template est approuvé
  4. Utilisez GET /templates pour lister les templates disponibles

​
Limitation de Requêtes

Problème : Too many requests Solutions :
  1. Implémentez un backoff exponentiel
  2. Respectez les en-têtes retry_after
  3. Regroupez les requêtes lorsque c’est possible
  4. Surveillez les modèles d’utilisation

​
Validation des Données

Problème : Validation failed Solutions :
  1. Validez les données avant l’envoi
  2. Utilisez le format de numéro de téléphone approprié
  3. Vérifiez le format de la date et l’heure
  4. Vérifiez que les champs requis sont présents
N’oubliez pas de toujours inclure le request_id lorsque vous contactez le support pour une résolution plus rapide des problèmes.