Pular para o conteúdo principal
Zenovay
Pro Plano10 minutesIntermediário

Erros de Conexão com a API

Solucione problemas de conexão com a API, falhas de autenticação e problemas de integração. Saiba mais sobre a API neste guia de solução de problemas.

apierrorsauthenticationintegrationdebugging
Última atualização:

Diagnostique e resolva erros de conexão com a API, falhas de autenticação e problemas de integração.

A API REST do Zenovay está disponível em planos pagos (Pro e superior). Chaves do plano gratuito são rejeitadas com uma resposta 403 API_PAID_PLAN_REQUIRED — atualize para usar chaves de API.

Erros de Autenticação

"Invalid API Key" (401)

Causas comuns:

  1. Formato de chave incorreto

    • A chave de API deve começar com o prefixo zv_
    • Chaves sem este prefixo são inválidas
    • Verifique se você copiou a chave completa do painel

  2. Chave revogada

    • Vá para Configurações → Conta → Segurança e acesso e abra a seção Chaves de API pessoais
    • Crie uma nova chave se a existente foi revogada

  3. Chave salva apenas uma vez

    • A chave completa é mostrada apenas no momento da criação — apenas o prefixo é armazenado depois
    • Se você não a copiou, crie uma nova chave

Correção:

// Incorreto - formato inválido
const key = 'abc123_not_valid...';

// Correto - chave de API do Zenovay
const key = 'zv_xyz789abc...';

"API Key Not Found" (401)

Verifique o formato do cabeçalho:

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

# Correto (API Externa)
curl -H "X-API-Key: zv_..."

"API requires a paid plan" (403)

A API REST é um recurso pago. Uma chave criada em (ou agora vinculada a) um plano gratuito retorna:

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

Correção: Atualize o time para Pro ou superior e crie a chave em Configurações → Conta → Segurança e acesso → Chaves de API pessoais.

"Access denied to this website" (403)

Uma chave de API pessoal tem dois escopos quando você a cria:

ConfiguraçãoOpções
PermissõesAcesso completo, ou apenas Leitura / Escrita / Admin
Acesso ao timeTodos os times a que você pertence, ou apenas times selecionados

Uma chave só pode acessar sites nos times aos quais tem permissão de agir (e apenas enquanto você ainda for membro desses times). Se uma solicitação retornar 403 para um site específico, o time que o possui provavelmente está fora do acesso do time da chave, ou você não pertence mais a esse time. Analise a chave em Configurações → Conta → Segurança e acesso → Chaves de API pessoais, ou crie uma chave com o acesso necessário.

Erros de Conexão

"Connection Refused"

Verifique o endpoint:

Correto: https://api.zenovay.com/api/external/v1/
Incorreto: http://api.zenovay.com/api/external/v1/  (sem HTTPS)
Incorreto: https://zenovay.com/api/    (domínio incorreto)

"Connection Timeout"

Causas:

  • Problemas de rede
  • Firewall bloqueando
  • Falha na resolução de DNS

Etapas de depuração:

  1. Teste a conectividade:

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

  2. Verifique DNS:

    nslookup api.zenovay.com

  3. Verifique o firewall:

    • Permitir HTTPS de saída (443)
    • Permitir domínio api.zenovay.com

"SSL Certificate Error"

Causas:

  • Certificados raiz desatualizados
  • Interferência de proxy corporativo
  • Desvio de relógio no servidor

Correção:

# Atualizar certificados (Ubuntu)
sudo apt update && sudo apt install ca-certificates

# Verifique a hora do sistema
date

# Se estiver usando Node.js, não desabilite a verificação:
// DON'T DO THIS IN PRODUCTION
// process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';

Erros de Limite de Taxa

"Rate Limit Exceeded" (429)

Cabeçalhos de resposta:

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

A API também retorna seu uso mensal em cada resposta:

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

Implemente backoff:

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 taxa da API REST

A API REST é limitada por chave, por nível de plano — tanto uma taxa por minuto quanto uma cota mensal de solicitações:

PlanoPor minutoPor mês
Pro30 req/min10.000
Scale60 req/min100.000
Enterprise120 req/min1.000.000

Exceder a taxa por minuto retorna 429 com Retry-After. Exceder a cota mensal retorna 429 e reseta no início do próximo mês (veja os cabeçalhos X-Usage-Monthly / X-Usage-Limit).

Limites de rastreamento e endpoints públicos

A ingestão de rastreamento e outros endpoints públicos são limitados por IP (não por plano), independentemente dos limites de chave de API REST:

ContextoLimite
Rastreamento (burst)60 req/10 sec por IP
Rastreamento (sustentado)5.000 req/hour por IP
Endpoints públicos30 req/min por IP
Endpoints de autenticação30 req/min por IP

Erros de Solicitação

"Bad Request" (400)

Problemas comuns:

  1. JSON inválido:

    // Incorreto - vírgula final
{ "name": "Test", }

// Correto
{ "name": "Test" }

  2. Parâmetros de consulta ausentes ou malformados:

    # Incorreto - intervalo de datas inválido
GET /api/external/v1/analytics/{websiteId}?from=yesterday

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

  3. Tipos de dados incorretos no corpo da solicitação:

    // Incorreto - string em vez de número
{ "page": "1" }

// Correto
{ "page": 1 }

"Not Found" (404)

Verifique:

  • A URL do endpoint está correta
  • O ID do recurso existe
  • O recurso pertence à sua conta
# Verifique o endpoint (note o prefixo /api/external/v1 e plural "websites")
GET /api/external/v1/websites/{websiteId}  # Correto
GET /api/external/v1/website/{websiteId}   # Incorreto (singular)

"Unprocessable Entity" (422)

Validação falhou. Verifique o corpo da resposta:

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

Erros de SDK

JavaScript SDK

"Zenovay not defined":

<!-- Certifique-se de que o script foi carregado -->
<script src="https://api.zenovay.com/z.js"
        data-tracking-code="YOUR_TRACKING_CODE"></script>

<!-- Verifique após carregar -->
<script>
  window.addEventListener('load', () => {
    if (typeof zenovay !== 'undefined') {
      console.log('Zenovay loaded');
    }
  });
</script>

Chamadas de API do lado do servidor

Problemas de conexão com o endpoint de rastreamento:

// Use fetch com o endpoint de rastreamento - nenhum pacote npm necessário.
// O endpoint de ingestão valida a carga útil, então envie o evento completo:
// session_id (mín. 8 caracteres), uma URL absoluta, user_agent e os
// campos de dispositivo (device_type, browser, os) são todos obrigatórios.
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);
}

Erros de timeout:

// Use AbortController para controle de timeout
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);

Dicas de Depuração

Ativar Modo de Depuração

Em chamadas do lado do servidor:

// Ative registro detalhado para chamadas de API externa
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());

Em script de rastreamento:

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

Verificar Status da API

  1. Visite status.zenovay.com
  2. Verifique o status do endpoint da API
  3. Revise o histórico de incidentes

Verificar atividade da chave

No painel:

  1. Vá para Configurações → Conta → Segurança e acesso e encontre suas Chaves de API pessoais
  2. Selecione uma chave para abrir sua visualização de detalhes
  3. Revise sua atividade — contagens de eventos aceitos nas últimas 24 horas, 7 dias e de todos os tempos, além de quando a chave foi usada pela última vez

Teste com cURL

# Teste a chave de API com o endpoint de uso
curl -H "X-API-Key: zv_..." \
     https://api.zenovay.com/api/external/v1/usage

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

# Com saída detalhada
curl -v -H "X-API-Key: zv_..." \
     https://api.zenovay.com/api/external/v1/websites

Códigos de Erro Comuns

CódigoSignificadoSolução
400Solicitação incorretaVerifique o corpo da solicitação
401Não autorizadoVerifique a chave de API
403ProibidoVerifique as permissões
404Não encontradoVerifique endpoint/ID
422Validação falhouVerifique valores dos campos
429Limite de taxa excedidoImplemente backoff
500Erro de servidorTente novamente, entre em contato com o suporte
502Gateway incorretoTente novamente em 1 minuto
503IndisponívelVerifique página de status

Contactar Suporte

Ao relatar problemas de API, inclua:

  1. Detalhes da solicitação:

    • URL do endpoint
    • Método HTTP
    • Cabeçalhos da solicitação (redija a chave de API)
    • Corpo da solicitação

  2. Detalhes da resposta:

    • Código de status
    • Corpo da resposta
    • Cabeçalhos da resposta

  3. Contexto:

    • Timestamp
    • ID da solicitação (dos cabeçalhos)
    • Versão do SDK, se aplicável

Email: [email protected]

Próximos Passos

Artigos relacionados

  1. Tratamento de Erros da API

    Trate erros da API do Zenovay de forma elegante — códigos de erro, estratégias de nova tentativa e técnicas de depuração. Saiba mais sobre tratamento de erros neste guia de integrações de API.

  2. Grupos de erros e agregação

    Entenda como o Zenovay agrupa erros similares e gerencie os fluxos de triagem de erros. Leia nosso guia de rastreamento de erros.

  3. Rastreamento de Erros JavaScript

    Capture e monitore automaticamente erros de JavaScript em todo o seu site com rastreamentos de pilha detalhados e contexto do usuário. Explore a configuração de rastreamento de erros e as melhores práticas.

Este artigo foi útil?