Saltar al contenido principal
Zenovaydocs
4 min de lectura

Cabecera Request ID

Cada respuesta de api.zenovay.com incluye una cabecera x-request-id. Es la única pieza de información que permite al soporte de Zenovay rastrear una llamada a la API específica desde tu cliente hasta los logs internos de la plataforma.

Cómo se ve

x-request-id: 01HVNXT7K8M3F2Y9R6P4ZQAB1C

Cada petición recibe un ULID único de 26 caracteres generado en el edge. El id también se etiqueta en cada informe de error que captura la monitorización de Zenovay, de modo que una única cadena conecta lo que vio tu cliente con lo que registraron los logs de la plataforma.

Cuándo aparece

  • En cada respuesta exitosa (2xx) — útil para depuración retroactiva si algo parecía erróneo a posteriori
  • En cada respuesta de error (4xx, 5xx) — el caso más útil; inclúyelo con tu ticket de soporte
  • Ingesta del tracker — las llamadas de pageview, event y revenue la llevan todas
  • Endpoints REST API y CLI — /api/external/v1/*, /v1/cli/*, MCP, etc.
  • Endpoints de autenticación — las llamadas a auth.zenovay.com también la incluyen

Cómo leerla desde tu código

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

Desde 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']);
}

Desde curl

Añade -i para imprimir las cabeceras de respuesta:

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

Cómo usarla con soporte

Cuando algo va mal:

  1. Captura el x-request-id de la respuesta fallida.
  2. Inclúyelo en tu ticket de soporte o publicación de la comunidad — literalmente, en un bloque de código.
  3. Anota la marca temporal UTC aproximada de la llamada (con precisión de un minuto suele bastar).
  4. Si puedes, incluye también la URL de la petición y el código de estado de la respuesta.

Con esas cuatro piezas de información, el soporte de Zenovay normalmente puede encontrar la llamada exacta en segundos y decirte por qué falló.

Consejos de logging

Para código de producción que llama a la API de Zenovay, captura x-request-id en cada ruta de error:

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

Si usas un logger estructurado (pino, winston, datadog, sentry, etc.), establece el request id como un campo estructurado en lugar de incrustarlo en el mensaje — así podrás buscarlo y agrupar por él.

CORS

x-request-id se expone a través de la cabecera de respuesta Access-Control-Expose-Headers en cada endpoint con CORS habilitado, de modo que los navegadores pueden leerlo desde JavaScript sin configuración adicional por tu parte.

Lo que no debes hacer con el request id

  • No intentes hacer ingeniería inversa para extraer información. Es un ULID, no un payload codificado.
  • No lo uses como clave de deduplicación — Zenovay gestiona la idempotencia de peticiones por separado, en los recursos que la necesitan.
  • No lo expongas en una superficie de cara al público (una página genérica de «Algo salió mal» está bien; una página de «La petición 01HVNX... falló» en un sitio de marketing público es más información de la que tus visitantes necesitan).

Relacionado

¿Fue útil esta página?