Límites de tasa y errores

Límites de tasa

Los límites se aplican por clave de API (o por cliente OAuth) y por minuto. Superar el límite devuelve 429 Too Many Requests.

¿Necesitas límites más altos para tu integración? Contacta con nuestro equipo.

Las sesiones en vivo abiertas a la vez son un límite aparte, no de tasa de peticiones: Free 1 sala, Pro 1 por licencia de presentador, Premium 2. Alcanzarlo devuelve 403 con el código session_limit. Cierra una sala desde Studio (o con POST /api/v1/sessions/{id}/control y end) antes de abrir otra.

Cabeceras de límite

Las respuestas JSON incluyen cabeceras con metadatos del límite:

X-RateLimit-Limit: 120
X-RateLimit-Window: 60s

Superar el límite devuelve 429 con el código rate_limited. Espera antes de reintentar. No hay cabecera Retry-After.

Formato de respuesta de error

Todos los errores de la API devuelven un cuerpo JSON con un objeto error anidado que contiene un code legible por máquina y un message legible por humanos:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "code": "not_found",
    "message": "Poll not found."
  }
}

Los errores de validación devuelven 422 con un campo details dentro del objeto de error:

{
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed.",
    "details": {
      "fieldErrors": { "title": ["String must contain at least 1 character(s)"] },
      "formErrors": []
    }
  }
}

Los errores del token OAuth siguen en cambio el formato RFC 6749 §5.2:

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials."
}

Códigos de error

Reintentos y espera

Recomendamos una estrategia de espera exponencial con variación aleatoria para integraciones en producción:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(url, options);

    if (res.status === 429) {
      // PollsLive does not send Retry-After, so back off exponentially
      // (capped at one minute, the length of a rate-limit window).
      const backoff = Math.min(1000 * 2 ** attempt + Math.random() * 500, 60000);
      await new Promise((r) => setTimeout(r, backoff));
      continue;
    }
    if (res.status >= 500 && attempt < maxRetries) {
      const backoff = Math.min(1000 * 2 ** attempt + Math.random() * 500, 30000);
      await new Promise((r) => setTimeout(r, backoff));
      continue;
    }
    return res;
  }
  throw new Error("Max retries exceeded");
}

No reintentes ante errores 4xx (salvo el 429): indican un problema en tu petición que no se resolverá reintentando.

Formato de error de OAuth

El endpoint de token (POST /api/oauth/token) devuelve errores en formato RFC 6749: