Guide de dépannage

Problèmes courants et solutions lors de l'intégration avec l'API de passerelle SMS Chinqit.

🔍 Étapes générales de dépannage

Vérifier la clé API : Assurez-vous que votre clé API est correcte et active
Vérifier le format de la requête : Vérifiez que le corps de votre requête correspond à la spécification de l'API
Examiner les messages d'erreur : Consultez la réponse d'erreur pour des détails spécifiques
Tester la connectivité : Assurez-vous que votre application peut accéder à https://sms.chinqit.com

🔐 Problèmes d'authentification

401 Unauthorized - Clé API manquante

Symptômes :

Code d'état 401
Message d'erreur "API key is required"

Solutions :

Vérifier le nom de l'en-tête

# Doit être exactement : X-API-Key (sensible à la casse)
curl -H "X-API-Key: your-key" https://sms.chinqit.com/messages/send

Vérifier le format de l'en-tête

// Correct
headers: {
  'X-API-Key': 'your-api-key'
}

// Incorrect - trait d'union manquant
headers: {
  'X_API_Key': 'your-api-key'
}

Vérifier que la clé API est incluse
- Vérifiez que votre clé API est envoyée dans chaque requête
- Assurez-vous qu'aucun middleware ne supprime l'en-tête

403 Forbidden - Clé API invalide

Symptômes :

Code d'état 403
Message d'erreur "Invalid API key"

Solutions :

Vérifier la clé API
- Contactez le support Chinqit pour confirmer que votre clé API est active
- Vérifiez les fautes de frappe ou les espaces supplémentaires dans votre clé API
- Assurez-vous d'utiliser la clé API correcte pour votre environnement

Vérifier le format de la clé API

# Assurez-vous qu'il n'y a pas d'espaces ou de caractères supplémentaires
# Correct : "abc123xyz"
# Incorrect : " abc123xyz " ou "abc123xyz\n"

Régénérer la clé API
- Si votre clé API a été compromise ou révoquée, demandez-en une nouvelle auprès de Chinqit

📝 Erreurs de validation

400 Bad Request - Erreur de validation

Symptômes :

Code d'état 400
Message "Validation failed" avec détails de l'erreur

Erreurs de validation courantes :

Champ obligatoire manquant :

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "path": ["phoneNumber"],
      "message": "Required"
    }
  ]
}

Format de numéro de téléphone invalide :

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "path": ["phoneNumber"],
      "message": "Invalid phone number format"
    }
  ]
}

Solutions :

Vérifier le corps de la requête

// Format correct pour l'envoi de SMS
{
  "phoneNumber": "+1234567890",
  "message": "Your message here"
}

// Format correct pour l'envoi d'OTP
{
  "phoneNumber": "+1234567890",
  "language": "en",
  "channel": "sms"
}

Vérifier le format du numéro de téléphone
- Doit inclure l'indicatif du pays avec le préfixe +
- Exemples : +1234567890, +33123456789
- Pas d'espaces ou de caractères spéciaux sauf +
Vérifier le contenu du message
- Le message doit contenir au moins 1 caractère
- L'OTP doit contenir exactement 6 chiffres
Vérifier la valeur du canal
- Pour l'OTP : channel doit être "sms" ou "whatsapp" (en minuscules)
- Par défaut "sms" si omis

📊 Limitation de débit

429 Too Many Requests

Symptômes :

Code d'état 429
Message d'erreur "Rate limit exceeded"

Limites de débit :

Envoi d'OTP : 3 requêtes par minute, 10 par heure, 20 par jour (par numéro de téléphone par clé API)

Solutions :

Implémenter un délai d'attente exponentiel

async function sendOTPWithRetry(
  phoneNumber,
  language,
  channel,
  maxRetries = 3,
) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await client.sendOTP(phoneNumber, language, channel);
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        // Attendre avec délai exponentiel
        const waitTime = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise((resolve) => setTimeout(resolve, waitTime));
        continue;
      }
      throw error;
    }
  }
}

Respecter les limites de débit
- Suivez la fréquence de vos requêtes
- Implémentez une limitation de débit côté client
- Attendez avant de réessayer après des erreurs 429
Utiliser différents numéros de téléphone
- Les limites de débit sont par numéro de téléphone
- Si vous testez, utilisez différents numéros de téléphone pour éviter d'atteindre les limites

📱 Problèmes de canal WhatsApp

502 Bad Gateway - Erreur du fournisseur WhatsApp

Symptômes :

Code d'état 502
Message d'erreur "WhatsApp OTP send failed"
Détails de l'erreur de l'API WhatsApp

Solutions :

Vérifier le format du numéro de téléphone
- WhatsApp requiert les numéros de téléphone au format E.164 avec l'indicatif du pays
- Exemple : +1234567890 (pas 1234567890)

Implémenter un repli vers SMS

async function sendOTPWithFallback(phoneNumber, language) {
  try {
    // Essayer WhatsApp en premier
    return await client.sendOTP(phoneNumber, language, "whatsapp");
  } catch (error) {
    if (error.status === 502) {
      // Repli vers SMS si WhatsApp échoue
      console.log("WhatsApp failed, falling back to SMS");
      return await client.sendOTP(phoneNumber, language, "sms");
    }
    throw error;
  }
}

Gérer les erreurs du fournisseur avec élégance
- Les erreurs du fournisseur WhatsApp sont temporaires
- Implémentez une logique de nouvelle tentative avec repli vers SMS
- Enregistrez les erreurs pour la surveillance
Vérifier la disponibilité du service WhatsApp
- Contactez le support Chinqit si le canal WhatsApp échoue constamment
- Vérifiez si le service WhatsApp est temporairement indisponible

🔄 Problèmes d'intégration courants

Messages non envoyés

Symptômes :

La requête réussit mais le message n'est pas reçu
Pas d'erreur mais pas de confirmation de livraison

Solutions :

Vérifier le numéro de téléphone
- Assurez-vous que le numéro de téléphone est correct et actif
- Vérifiez que l'indicatif du pays est correct
- Vérifiez que le destinataire peut recevoir des SMS
Vérifier le contenu du message
- Assurez-vous que le message n'est pas vide
- Vérifiez que les caractères spéciaux sont correctement encodés
- Vérifiez la longueur du message (les limites SMS standard s'appliquent)
Gérer le traitement asynchrone
- Les messages sont mis en file d'attente et traités de manière asynchrone
- L'API retourne immédiatement après la mise en file d'attente
- La livraison peut prendre quelques secondes à quelques minutes

Échec de la vérification OTP

Symptômes :

L'OTP est envoyé avec succès mais la vérification échoue
Erreurs "Invalid OTP" ou "OTP not found"

Solutions :

Vérifier l'expiration de l'OTP
- Les OTP expirent après 10 minutes
- Assurez-vous que l'utilisateur entre l'OTP rapidement
- Demandez un nouvel OTP s'il est expiré
Vérifier le format de l'OTP
- L'OTP doit contenir exactement 6 chiffres
- Pas d'espaces ou de caractères spéciaux
- Exemple : "123456" (pas "123 456" ou "123-456")
Vérifier la limite de tentatives
- Maximum 3 tentatives de vérification par OTP
- Après 3 échecs, l'OTP est invalidé
- Demandez un nouvel OTP si la limite de tentatives est dépassée
Faire correspondre le canal
- Si l'OTP a été envoyé via WhatsApp, vérifiez avec channel: "whatsapp"
- Si l'OTP a été envoyé via SMS, vérifiez avec channel: "sms" (ou omettez, par défaut SMS)
Gérer la sensibilité à la casse
- Le numéro de téléphone doit correspondre exactement (y compris le préfixe +)
- Assurez-vous que le format du numéro de téléphone est cohérent entre l'envoi et la vérification

🌐 Problèmes réseau

Délai de connexion dépassé

Symptômes :

Expiration de la requête
Erreurs réseau

Solutions :

Vérifier la connexion Internet
- Vérifiez que votre application a accès à Internet
- Testez la connectivité à https://sms.chinqit.com

Implémenter la gestion des délais d'attente

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 10000); // Délai de 10 secondes

try {
  const response = await fetch("https://sms.chinqit.com/messages/send", {
    signal: controller.signal,
    // ... autres options
  });
  clearTimeout(timeoutId);
} catch (error) {
  if (error.name === "AbortError") {
    console.error("Request timeout");
  }
}

Logique de nouvelle tentative
- Implémentez une logique de nouvelle tentative pour les erreurs réseau transitoires
- Utilisez un délai d'attente exponentiel
- Ne réessayez pas sur les erreurs 4xx (erreurs client)

Erreurs SSL/TLS

Symptômes :

Erreurs de certificat SSL
Échecs de négociation TLS

Solutions :

Vérifier HTTPS
- Utilisez toujours https://sms.chinqit.com (pas http://)
- Assurez-vous que votre environnement supporte TLS 1.2+
Vérifier le certificat
- Assurez-vous que l'horloge système est correcte
- Mettez à jour les certificats CA si nécessaire
- Contactez Chinqit si les problèmes de certificat persistent

🐛 Conseils de débogage

Activer la journalisation des requêtes

JavaScript :

async function sendMessage(phoneNumber, message) {
  console.log("Sending message:", { phoneNumber, message });

  try {
    const response = await fetch("https://sms.chinqit.com/messages/send", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": process.env.API_KEY,
      },
      body: JSON.stringify({ phoneNumber, message }),
    });

    console.log("Response status:", response.status);
    const data = await response.json();
    console.log("Response data:", data);

    return data;
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

Python :

import requests
import logging

logging.basicConfig(level=logging.DEBUG)

def send_message(phone_number, message):
    url = 'https://sms.chinqit.com/messages/send'
    headers = {
        'Content-Type': 'application/json',
        'X-API-Key': os.getenv('API_KEY')
    }
    data = {
        'phoneNumber': phone_number,
        'message': message
    }

    logging.debug(f'Sending request: {data}')
    response = requests.post(url, json=data, headers=headers)
    logging.debug(f'Response status: {response.status_code}')
    logging.debug(f'Response data: {response.json()}')

    return response.json()

Tester la connectivité de l'API

# Tester la connectivité de base
curl -X POST https://sms.chinqit.com/messages/send \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+1234567890", "message": "Test"}'

🆘 Vous avez toujours des problèmes ?

Consultez la documentation :
- Référence API - Documentation complète des points de terminaison
- Guide d'utilisation de l'API - Exemples de code
Examinez les réponses d'erreur :
- Vérifiez le champ message pour des détails d'erreur spécifiques
- Consultez le tableau errors pour les problèmes de validation
- Notez le code d'état HTTP
Solutions courantes :
- Vérifiez que la clé API est correcte et active
- Vérifiez que le format de la requête correspond à la spécification de l'API
- Assurez-vous que les numéros de téléphone sont au format E.164
- Implémentez une gestion appropriée des erreurs et une logique de nouvelle tentative
- Contactez le support Chinqit pour les problèmes persistants

Besoin d'aide supplémentaire ? Contactez le support Chinqit avec :

Votre clé API (masquée)
Message d'erreur et code d'état
Détails de la requête (sans données sensibles)
Étapes pour reproduire le problème

🔍 Étapes générales de dépannage​

🔐 Problèmes d'authentification​

401 Unauthorized - Clé API manquante​

403 Forbidden - Clé API invalide​

📝 Erreurs de validation​

400 Bad Request - Erreur de validation​

📊 Limitation de débit​

429 Too Many Requests​

📱 Problèmes de canal WhatsApp​

502 Bad Gateway - Erreur du fournisseur WhatsApp​

🔄 Problèmes d'intégration courants​

Messages non envoyés​

Échec de la vérification OTP​

🌐 Problèmes réseau​

Délai de connexion dépassé​

Erreurs SSL/TLS​

🐛 Conseils de débogage​

Activer la journalisation des requêtes​

Tester la connectivité de l'API​

🆘 Vous avez toujours des problèmes ?​

🔍 Étapes générales de dépannage

🔐 Problèmes d'authentification

401 Unauthorized - Clé API manquante

403 Forbidden - Clé API invalide

📝 Erreurs de validation

400 Bad Request - Erreur de validation

📊 Limitation de débit

429 Too Many Requests

📱 Problèmes de canal WhatsApp

502 Bad Gateway - Erreur du fournisseur WhatsApp

🔄 Problèmes d'intégration courants

Messages non envoyés

Échec de la vérification OTP

🌐 Problèmes réseau

Délai de connexion dépassé

Erreurs SSL/TLS

🐛 Conseils de débogage

Activer la journalisation des requêtes

Tester la connectivité de l'API

🆘 Vous avez toujours des problèmes ?