Aller au contenu principal
Zenovay
Pro Plan10 minutesIntermédiaire

Erreurs de connexion à l'API

Dépannez les problèmes de connexion à l'API, les échecs d'authentification et les problèmes d'intégration. Découvrez l'API dans ce guide de dépannage.

apierrorsauthenticationintegrationdebugging
Dernière mise à jour :

Diagnostiquez et résolvez les problèmes de connexion à l'API, les échecs d'authentification et les problèmes d'intégration.

L'API REST Zenovay est disponible sur les forfaits payants (Pro et supérieur). Les clés du forfait gratuit sont rejetées avec une réponse 403 API_PAID_PLAN_REQUIRED — mettez à niveau pour utiliser les clés API.

Erreurs d'authentification

"Invalid API Key" (401)

Causes communes:

  1. Format de clé incorrect

    • La clé API doit commencer par le préfixe zv_
    • Les clés sans ce préfixe sont invalides
    • Vérifiez que vous avez copié la clé complète depuis le tableau de bord

  2. Clé révoquée

    • Allez à Paramètres → Compte → Sécurité et accès et ouvrez la section Clés API personnelles
    • Créez une nouvelle clé si la clé existante a été révoquée

  3. Clé sauvegardée une seule fois

    • La clé complète n'est affichée qu'au moment de la création — seul le préfixe est stocké après
    • Si vous ne l'avez pas copiée, créez une nouvelle clé

Correction:

// Incorrect - format invalide
const key = 'abc123_not_valid...';

// Correct - clé API Zenovay
const key = 'zv_xyz789abc...';

"API Key Not Found" (401)

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

# Incorrect
curl -H "Api-Key: zv_..."

# Correct (API externe)
curl -H "X-API-Key: zv_..."

"API requires a paid plan" (403)

L'API REST est une fonctionnalité payante. Une clé créée sur (ou maintenant liée à) un forfait gratuit retourne:

{
  "error": "The Zenovay API requires a paid plan. Upgrade to Pro or higher to use API keys.",
  "code": "API_PAID_PLAN_REQUIRED"
}

Correction: Mettez à niveau l'équipe vers Pro ou supérieur, puis créez la clé sous Paramètres → Compte → Sécurité et accès → Clés API personnelles.

"Access denied to this website" (403)

Une clé API personnelle a deux portées lorsque vous la créez:

ParamètreOptions
PermissionsAccès complet, ou seulement Lecture / Écriture / Admin
Accès à l'équipeToutes les équipes auxquelles vous appartenez, ou seulement les équipes sélectionnées

Une clé ne peut accéder aux sites web que dans les équipes auxquelles elle est autorisée à agir (et seulement tant que vous êtes toujours membre de ces équipes). Si une demande retourne 403 pour un site web spécifique, l'équipe qui la possède est probablement en dehors de l'accès à l'équipe de la clé, ou vous n'appartenez plus à cette équipe. Examinez la clé sous Paramètres → Compte → Sécurité et accès → Clés API personnelles, ou créez une clé avec l'accès dont vous avez besoin.

Erreurs de connexion

"Connection Refused"

Vérifiez le point de terminaison:

Correct: https://api.zenovay.com/api/external/v1/
Incorrect: http://api.zenovay.com/api/external/v1/  (pas de HTTPS)
Incorrect: https://zenovay.com/api/    (mauvais domaine)

"Connection Timeout"

Causes:

  • Problèmes de réseau
  • Pare-feu bloquant
  • Échec de la résolution DNS

Étapes de débogage:

  1. Tester la connectivité:

    curl -v https://api.zenovay.com/api/external/v1/usage

  2. Vérifier DNS:

    nslookup api.zenovay.com

  3. Vérifier le pare-feu:

    • Autoriser HTTPS sortant (443)
    • Autoriser le domaine api.zenovay.com

"SSL Certificate Error"

Causes:

  • Certificats racine obsolètes
  • Interférence du proxy d'entreprise
  • Décalage d'horloge sur le serveur

Correction:

# Mettre à jour les certificats (Ubuntu)
sudo apt update && sudo apt install ca-certificates

# Vérifier l'heure système
date

# Si vous utilisez Node.js, n'désactivez pas la vérification:
// DON'T DO THIS IN PRODUCTION
// process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';

Erreurs de limite de débit

"Rate Limit Exceeded" (429)

En-têtes de réponse:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-06-13T12:01:00.000Z
Retry-After: 42

L'API retourne également votre utilisation mensuelle sur chaque réponse:

X-Usage-Monthly: 4231
X-Usage-Limit: 10000

Implémentez l'attente exponentielle:

async function apiCallWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429) {
        const retryAfter = error.headers.get('Retry-After') || 60;
        await sleep(retryAfter * 1000);
        continue;
      }
      throw error;
    }
  }
}

Limites de taux de l'API REST

L'API REST est limitée par clé, selon le niveau du forfait — à la fois un débit par minute et un quota mensuel de demandes:

ForfaitPar minutePar mois
Pro30 req/min10 000
Scale60 req/min100 000
Enterprise120 req/min1 000 000

Dépasser le débit par minute retourne 429 avec Retry-After. Dépasser le quota mensuel retourne 429 et se réinitialise au début du mois suivant (voir les en-têtes X-Usage-Monthly / X-Usage-Limit).

Limites des points de terminaison de suivi et publics

L'ingestion de suivi et d'autres points de terminaison publics sont limités par adresse IP (pas par forfait), indépendamment des limites de clé API REST:

ContexteLimite
Suivi (burst)60 req/10 sec par IP
Suivi (soutenu)5 000 req/hour par IP
Points de terminaison publics30 req/min par IP
Points de terminaison d'authentification30 req/min par IP

Erreurs de demande

"Bad Request" (400)

Problèmes courants:

  1. JSON invalide:

    // Incorrect - virgule finale
{ "name": "Test", }

// Correct
{ "name": "Test" }

  2. Paramètres de requête manquants ou mal formés:

    # Incorrect - plage de dates invalide
GET /api/external/v1/analytics/{websiteId}?from=yesterday

# Correct - dates ISO
GET /api/external/v1/analytics/{websiteId}?from=2026-06-01&to=2026-06-13

  3. Mauvais types de données dans le corps de la demande:

    // Incorrect - chaîne au lieu de nombre
{ "page": "1" }

// Correct
{ "page": 1 }

"Not Found" (404)

Vérifiez:

  • L'URL du point de terminaison est correcte
  • L'ID de ressource existe
  • La ressource vous appartient
# Vérifier le point de terminaison (notez le préfixe /api/external/v1 et le pluriel "websites")
GET /api/external/v1/websites/{websiteId}  # Correct
GET /api/external/v1/website/{websiteId}   # Incorrect (singulier)

"Unprocessable Entity" (422)

La validation a échoué. Vérifiez le corps de la réponse:

{
  "error": "validation_error",
  "details": {
    "url": "Invalid URL format",
    "name": "Name too long (max 100 characters)"
  }
}

Erreurs SDK

JavaScript SDK

"Zenovay not defined":

<!-- Assurez-vous que le script est chargé -->
<script src="https://api.zenovay.com/z.js"
        data-tracking-code="YOUR_TRACKING_CODE"></script>

<!-- Vérifier après le chargement -->
<script>
  window.addEventListener('load', () => {
    if (typeof zenovay !== 'undefined') {
      console.log('Zenovay loaded');
    }
  });
</script>

Appels API côté serveur

Problèmes de connexion avec le point de terminaison de suivi:

// Utilisez fetch avec le point de terminaison de suivi - aucun paquet npm nécessaire.
// Le point de terminaison d'ingestion valide la charge utile, donc envoyez l'événement complet:
// session_id (min 8 caractères), une URL absolue, user_agent et les
// champs de dispositif (device_type, browser, os) sont tous requis.
const response = await fetch('https://api.zenovay.com/e/YOUR_TRACKING_CODE', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    event_type: 'pageview',
    url: 'https://example.com/home',
    session_id: 'srv-session-abcdef',
    user_agent: 'MyServer/1.0',
    device_type: 'desktop',
    browser: 'Server',
    os: 'Linux',
  }),
});

if (!response.ok) {
  console.error('Zenovay tracking error:', response.status);
}

Erreurs de délai d'expiration:

// Utilisez AbortController pour le contrôle du délai d'expiration
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 30000);

const response = await fetch('https://api.zenovay.com/e/YOUR_TRACKING_CODE', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    event_type: 'pageview',
    url: 'https://example.com/home',
    session_id: 'srv-session-abcdef',
    user_agent: 'MyServer/1.0',
    device_type: 'desktop',
    browser: 'Server',
    os: 'Linux',
  }),
  signal: controller.signal,
});

clearTimeout(timeout);

Conseils de débogage

Activer le mode débogage

Dans les appels côté serveur:

// Activez la journalisation détaillée pour les appels API externes
const response = await fetch('https://api.zenovay.com/api/external/v1/websites', {
  headers: { 'X-API-Key': 'zv_...' },
});
console.log('Status:', response.status);
console.log('Response:', await response.json());

Dans le script de suivi:

<script data-tracking-code="YOUR_TRACKING_CODE"
        data-debug="true"
        src="..."></script>

Vérifier l'état de l'API

  1. Visitez status.zenovay.com
  2. Vérifiez l'état du point de terminaison API
  3. Passez en revue l'historique des incidents

Vérifier l'activité des clés

Dans le tableau de bord:

  1. Allez à Paramètres → Compte → Sécurité et accès et trouvez vos Clés API personnelles
  2. Sélectionnez une clé pour ouvrir sa vue détaillée
  3. Examinez son activité — comptes d'événements acceptés au cours des 24 dernières heures, 7 jours et de tous les temps, ainsi que la dernière utilisation de la clé

Tester avec cURL

# Tester la clé API avec le point de terminaison d'utilisation
curl -H "X-API-Key: zv_..." \
     https://api.zenovay.com/api/external/v1/usage

# Lister les sites web
curl -H "X-API-Key: zv_..." \
     https://api.zenovay.com/api/external/v1/websites

# Avec une sortie détaillée
curl -v -H "X-API-Key: zv_..." \
     https://api.zenovay.com/api/external/v1/websites

Codes d'erreur courants

CodeSignificationSolution
400Mauvaise demandeVérifier le corps de la demande
401Non autoriséVérifier la clé API
403InterditVérifier les permissions
404Non trouvéVérifier le point de terminaison/ID
422Échec de la validationVérifier les valeurs des champs
429Limité par débitImplémenter l'attente exponentielle
500Erreur serveurRéessayer, contacter le support
502Mauvaise passerelleRéessayer dans 1 minute
503IndisponibleVérifier la page d'état

Contacter le support

Lors de la signalisation de problèmes d'API, incluez:

  1. Détails de la demande:

    • URL du point de terminaison
    • Méthode HTTP
    • En-têtes de la demande (masquer la clé API)
    • Corps de la demande

  2. Détails de la réponse:

    • Code d'état
    • Corps de la réponse
    • En-têtes de réponse

  3. Contexte:

    • Horodatage
    • ID de demande (des en-têtes)
    • Version SDK le cas échéant

Email: [email protected]

Prochaines étapes

Articles connexes

  1. Gestion des erreurs de l'API

    Gérez gracieusement les erreurs de l'API Zenovay — codes d'erreur, stratégies de réessai et techniques de débogage. Apprenez la gestion des erreurs dans ce guide sur les intégrations d'API.

  2. Groupes d'erreurs et agrégation

    Comprenez comment Zenovay regroupe les erreurs similaires et gérez les flux de triage des erreurs. Lisez notre guide de suivi des erreurs.

  3. Suivi des erreurs JavaScript

    Capturez et surveillez automatiquement les erreurs JavaScript sur votre site web avec des traces de pile détaillées et le contexte utilisateur. Explorez la configuration du suivi des erreurs et les meilleures pratiques.

Cet article vous a-t-il aidé ?