Ir al contenido principal
Zenovay
Pro Plan10 minutesIntermedio

Errores de conexión a la API

Diagnostica problemas de conexión a la API, fallos de autenticación y problemas de integración. Obtén más información sobre la API en esta guía de solución de problemas.

apierrorsauthenticationintegrationdebugging
Última actualización:

Diagnostica y resuelve errores de conexión a la API, fallos de autenticación y problemas de integración.

La API REST de Zenovay está disponible en planes de pago (Pro y superior). Las claves del plan gratuito se rechazan con una respuesta 403 API_PAID_PLAN_REQUIRED — actualiza para usar claves API.

Errores de autenticación

"Invalid API Key" (401)

Causas comunes:

  1. Formato de clave incorrecto

    • La clave API debe comenzar con el prefijo zv_
    • Las claves sin este prefijo son inválidas
    • Verifica que hayas copiado la clave completa desde el panel

  2. Clave revocada

    • Ve a Configuración → Cuenta → Seguridad y acceso y abre la sección Claves API personales
    • Crea una nueva clave si la existente ha sido revocada

  3. Clave guardada una sola vez

    • La clave completa se muestra solo en el momento de la creación — solo el prefijo se almacena después
    • Si no la copiaste, crea una nueva clave

Solución:

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

// Correcto - clave API de Zenovay
const key = 'zv_xyz789abc...';

"API Key Not Found" (401)

Verifica el formato del encabezado:

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

# Correcto (API externa)
curl -H "X-API-Key: zv_..."

"API requires a paid plan" (403)

La API REST es una función de pago. Una clave creada en (o ahora vinculada a) un plan gratuito devuelve:

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

Solución: Actualiza el equipo a Pro o superior y luego crea la clave bajo Configuración → Cuenta → Seguridad y acceso → Claves API personales.

"Access denied to this website" (403)

Una clave API personal tiene dos ámbitos cuando la creas:

ConfiguraciónOpciones
PermisosAcceso completo, o solo Leer / Escribir / Admin
Acceso al equipoTodos los equipos a los que perteneces, o solo equipos seleccionados

Una clave solo puede acceder a sitios web en los equipos a los que se le permite actuar (y solo mientras siga siendo miembro de esos equipos). Si una solicitud devuelve 403 para un sitio web específico, es probable que el equipo que lo posee esté fuera del acceso del equipo de la clave, o ya no perteneces a ese equipo. Revisa la clave bajo Configuración → Cuenta → Seguridad y acceso → Claves API personales, o crea una clave con el acceso que necesitas.

Errores de conexión

"Connection Refused"

Verifica el punto final:

Correcto: https://api.zenovay.com/api/external/v1/
Incorrecto: http://api.zenovay.com/api/external/v1/  (sin HTTPS)
Incorrecto: https://zenovay.com/api/    (dominio incorrecto)

"Connection Timeout"

Causas:

  • Problemas de red
  • Firewall bloqueando
  • Fallo en la resolución DNS

Pasos de depuración:

  1. Prueba la conectividad:

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

  2. Verifica DNS:

    nslookup api.zenovay.com

  3. Verifica el firewall:

    • Permitir HTTPS saliente (443)
    • Permitir dominio api.zenovay.com

"SSL Certificate Error"

Causas:

  • Certificados raíz desactualizados
  • Interferencia del proxy corporativo
  • Desviación de reloj en el servidor

Solución:

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

# Verifica la hora del sistema
date

# Si usas Node.js, no desactives la verificación:
// DON'T DO THIS IN PRODUCTION
// process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';

Errores de límite de tasa

"Rate Limit Exceeded" (429)

Encabezados de respuesta:

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

La API también devuelve tu uso mensual en cada respuesta:

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

Implementa 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;
    }
  }
}

Límites de tasa de la API REST

La API REST está limitada por clave, por nivel de plan — tanto una tasa por minuto como una cuota mensual de solicitudes:

PlanPor minutoPor mes
Pro30 req/min10.000
Scale60 req/min100.000
Enterprise120 req/min1.000.000

Exceder la tasa por minuto devuelve 429 con Retry-After. Exceder la cuota mensual devuelve 429 y se reinicia al comienzo del próximo mes (ver encabezados X-Usage-Monthly / X-Usage-Limit).

Límites de seguimiento y puntos finales públicos

La ingesta de seguimiento y otros puntos finales públicos están limitados por IP (no por plan), independientemente de los límites de clave de API REST:

ContextoLímite
Seguimiento (ráfaga)60 req/10 sec por IP
Seguimiento (sostenido)5.000 req/hour por IP
Puntos finales públicos30 req/min por IP
Puntos finales de autenticación30 req/min por IP

Errores de solicitud

"Bad Request" (400)

Problemas comunes:

  1. JSON inválido:

    // Incorrecto - coma final
{ "name": "Test", }

// Correcto
{ "name": "Test" }

  2. Parámetros de consulta faltantes o mal formados:

    # Incorrecto - rango de fechas inválido
GET /api/external/v1/analytics/{websiteId}?from=yesterday

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

  3. Tipos de datos incorrectos en el cuerpo de la solicitud:

    // Incorrecto - cadena en lugar de número
{ "page": "1" }

// Correcto
{ "page": 1 }

"Not Found" (404)

Verifica:

  • La URL del punto final es correcta
  • El ID de recurso existe
  • El recurso te pertenece
# Verifica el punto final (nota el prefijo /api/external/v1 y plural "websites")
GET /api/external/v1/websites/{websiteId}  # Correcto
GET /api/external/v1/website/{websiteId}   # Incorrecto (singular)

"Unprocessable Entity" (422)

Validación fallida. Verifica el cuerpo de la respuesta:

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

Errores de SDK

JavaScript SDK

"Zenovay not defined":

<!-- Asegúrate de que el script se cargue -->
<script src="https://api.zenovay.com/z.js"
        data-tracking-code="YOUR_TRACKING_CODE"></script>

<!-- Verifica después de cargar -->
<script>
  window.addEventListener('load', () => {
    if (typeof zenovay !== 'undefined') {
      console.log('Zenovay loaded');
    }
  });
</script>

Llamadas API del lado del servidor

Problemas de conexión con el punto final de seguimiento:

// Usa fetch con el punto final de seguimiento - no se necesita paquete npm.
// El punto final de ingesta valida la carga útil, así que envía el evento completo:
// session_id (mín. 8 caracteres), una URL absoluta, user_agent y los
// campos de dispositivo (device_type, browser, os) son todos requeridos.
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);
}

Errores de tiempo de espera:

// Usa AbortController para control de tiempo de espera
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);

Consejos de depuración

Activar modo de depuración

En llamadas del lado del servidor:

// Activa registro detallado para llamadas API externas
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());

En script de seguimiento:

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

Verifica el estado de la API

  1. Visita status.zenovay.com
  2. Verifica el estado del punto final API
  3. Revisa el historial de incidentes

Verifica la actividad de claves

En el panel:

  1. Ve a Configuración → Cuenta → Seguridad y acceso y encuentra tus Claves API personales
  2. Selecciona una clave para abrir su vista de detalles
  3. Revisa su actividad — recuentos de eventos aceptados durante las últimas 24 horas, 7 días y todo el tiempo, además de cuándo se usó por última vez la clave

Prueba con cURL

# Prueba la clave API con el punto final de uso
curl -H "X-API-Key: zv_..." \
     https://api.zenovay.com/api/external/v1/usage

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

# Con salida detallada
curl -v -H "X-API-Key: zv_..." \
     https://api.zenovay.com/api/external/v1/websites

Códigos de error comunes

CódigoSignificadoSolución
400Solicitud incorrectaVerifica el cuerpo de la solicitud
401No autorizadoVerifica la clave API
403ProhibidoVerifica permisos
404No encontradoVerifica punto final/ID
422Validación fallidaVerifica valores de campos
429Límite de tasa excedidoImplementa backoff
500Error de servidorReintentar, contactar soporte
502Puerta de enlace incorrectaReintentar en 1 minuto
503No disponibleVerifica página de estado

Contactar soporte

Al reportar problemas de API, incluye:

  1. Detalles de solicitud:

    • URL del punto final
    • Método HTTP
    • Encabezados de solicitud (redacta clave API)
    • Cuerpo de solicitud

  2. Detalles de respuesta:

    • Código de estado
    • Cuerpo de respuesta
    • Encabezados de respuesta

  3. Contexto:

    • Marca de tiempo
    • ID de solicitud (de encabezados)
    • Versión de SDK si corresponde

Email: [email protected]

Próximos pasos

Artículos relacionados

  1. Manejo de errores de la API

    Gestiona los errores de la API de Zenovay de forma elegante — códigos de error, estrategias de reintento y técnicas de depuración. Aprende sobre manejo de errores en esta guía de integraciones de API.

  2. Grupos de errores y agregación

    Comprende cómo Zenovay agrupa errores similares y gestiona los flujos de trabajo de clasificación de errores. Lee nuestra guía de seguimiento de errores.

  3. Seguimiento de errores JavaScript

    Captura y monitorea automáticamente los errores de JavaScript en tu sitio web con trazas de pila detalladas y contexto del usuario. Explora la configuración del seguimiento de errores y las mejores prácticas.

¿Fue útil este artículo?