Pular para o conteúdo principal
Zenovaydocs
4 min de leitura

Header Request ID

Toda resposta de api.zenovay.com inclui um header x-request-id. É a única informação que permite ao suporte do Zenovay rastrear uma chamada de API específica desde o seu cliente até os logs internos da plataforma.

Como ele se parece

x-request-id: 01HVNXT7K8M3F2Y9R6P4ZQAB1C

Cada requisição recebe um ULID único de 26 caracteres gerado no edge. O id também é marcado em todo relatório de erro que o monitoramento do Zenovay captura, de modo que uma única string conecta o que seu cliente viu e o que os logs da plataforma registraram.

Quando ele aparece

  • Em toda resposta bem-sucedida (2xx) — útil para depuração retroativa caso algo pareça errado depois do fato
  • Em toda resposta de erro (4xx, 5xx) — o caso mais útil; inclua-o no seu ticket de suporte
  • Ingestão do tracker — chamadas de pageview, event e revenue carregam todas ele
  • Endpoints da REST API e do CLI — /api/external/v1/*, /v1/cli/*, MCP, etc.
  • Endpoints de autenticação — chamadas a auth.zenovay.com também o incluem

Como lê-lo a partir do seu código

A partir de respostas 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);
}

A partir do 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']);
}

A partir do curl

Adicione -i para imprimir os headers de resposta:

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

Como usá-lo com o suporte

Quando algo der errado:

  1. Capture o x-request-id da resposta que falhou.
  2. Inclua-o no seu ticket de suporte ou postagem da comunidade — literalmente, em um bloco de código.
  3. Anote o timestamp UTC aproximado da chamada (com precisão de um minuto geralmente é suficiente).
  4. Se possível, inclua também a URL da requisição e o código de status da resposta.

Com essas quatro informações, o suporte do Zenovay normalmente consegue localizar a chamada exata em segundos e dizer por que ela falhou.

Dicas de logging

Para código de produção que chama a API do Zenovay, capture x-request-id em cada caminho de erro:

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

Se você usa um logger estruturado (pino, winston, datadog, sentry, etc.), defina o request id como um campo estruturado em vez de embuti-lo na mensagem — assim você pode pesquisar e agrupar por ele.

CORS

x-request-id é exposto via o header de resposta Access-Control-Expose-Headers em todo endpoint com CORS habilitado, então os navegadores podem lê-lo a partir do JavaScript sem nenhuma configuração extra do seu lado.

O que você não deve fazer com o request id

  • Não tente fazer engenharia reversa para extrair informações dele. É um ULID, não um payload codificado.
  • Não o use como chave de deduplicação — o Zenovay lida com idempotência de requisições separadamente, nos recursos que precisam dela.
  • Não o exponha em uma superfície voltada ao público (uma página genérica de "Algo deu errado" tudo bem; uma página de "Requisição 01HVNX... falhou" em um site de marketing público é mais informação do que seus visitantes precisam).

Relacionado

Esta página foi útil?