4 min de lecture

En-tête Request ID

Chaque réponse de api.zenovay.com inclut un en-tête x-request-id. C'est la seule information qui permet au support Zenovay de tracer un appel API spécifique depuis votre client jusque dans les logs internes de la plateforme.

À quoi il ressemble

x-request-id: 01HVNXT7K8M3F2Y9R6P4ZQAB1C

Chaque requête reçoit un ULID unique de 26 caractères généré à l'edge. L'id est également associé à chaque rapport d'erreur que la surveillance de Zenovay capture, de sorte qu'une seule chaîne relie ce que votre client a vu et ce que les logs de la plateforme ont enregistré.

Quand il apparaît

Sur chaque réponse réussie (2xx) — utile pour le débogage rétroactif si quelque chose semblait incorrect après coup
Sur chaque réponse d'erreur (4xx, 5xx) — le cas le plus utile ; incluez-le avec votre ticket de support
Ingestion par le tracker — les appels pageview, event et revenue le portent tous
Endpoints REST API et CLI — /api/external/v1/*, /v1/cli/*, MCP, etc.
Endpoints d'authentification — les appels à auth.zenovay.com l'incluent également

Comment le lire depuis votre code

Depuis les réponses `fetch`

const response = await fetch('https://api.zenovay.com/api/external/v1/...', {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const requestId = response.headers.get('x-request-id');

if (!response.ok) {
  console.error(`Zenovay API error (request ${requestId}):`, response.status);
}

Depuis `axios`

try {
  const result = await axios.get('https://api.zenovay.com/api/external/v1/...', {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  console.log('request id:', result.headers['x-request-id']);
} catch (err) {
  console.error('failed; request id:', err.response?.headers?.['x-request-id']);
}

Depuis `curl`

Ajoutez -i pour afficher les en-têtes de réponse :

curl -i https://api.zenovay.com/api/external/v1/analytics/<websiteId>/visitors \
  -H "Authorization: Bearer YOUR_KEY"

Comment l'utiliser avec le support

Quand quelque chose ne va pas :

Capturez le x-request-id depuis la réponse en échec.
Incluez-le dans votre ticket de support ou votre publication communautaire — verbatim, dans un bloc de code.
Notez l'horodatage UTC approximatif de l'appel (à la minute près suffit en général).
Si vous le pouvez, incluez l'URL de la requête et le code de statut de la réponse.

Avec ces quatre informations, le support Zenovay peut généralement retrouver l'appel exact en quelques secondes et vous indiquer pourquoi il a échoué.

Conseils de logging

Pour le code de production qui appelle l'API Zenovay, capturez x-request-id sur chaque chemin d'erreur :

function logZenovayError(label, response) {
  const requestId = response.headers.get('x-request-id') ?? 'unknown';
  console.error(`[zenovay:${label}] status=${response.status} req=${requestId}`);
}

Si vous utilisez un logger structuré (pino, winston, datadog, sentry, etc.), définissez le request id comme un champ structuré plutôt que de l'intégrer dans le message — ainsi vous pourrez rechercher et regrouper par cet identifiant.

CORS

x-request-id est exposé via l'en-tête de réponse Access-Control-Expose-Headers sur chaque endpoint compatible CORS, afin que les navigateurs puissent le lire depuis JavaScript sans aucune configuration supplémentaire de votre côté.

Ce que vous ne devez pas faire avec le request id

N'essayez pas d'en faire de la rétro-ingénierie pour en extraire des informations. C'est un ULID, pas une charge utile encodée.
Ne l'utilisez pas comme clé de déduplication — Zenovay gère l'idempotence des requêtes séparément, sur les ressources qui en ont besoin.
Ne l'exposez pas sur une surface publique (une page générique « Une erreur est survenue » convient ; une page « La requête 01HVNX... a échoué » sur un site marketing public donne plus d'informations que ce dont vos visiteurs ont besoin).