Limites de taxa e erros

Limites de taxa

Os limites são aplicados por chave de API (ou por cliente OAuth) e por minuto. Exceder o limite retorna 429 Too Many Requests.

Precisa de limites maiores para sua integração? Fale com nossa equipe.

Sessões ao vivo abertas ao mesmo tempo são um teto separado, não um limite de taxa: Free 1 sala, Pro 1 por licença de apresentador, Premium 2. Ao atingi-lo, retorna 403 com o código session_limit. Encerre uma sala pelo Studio (ou com POST /api/v1/sessions/{id}/control e end) antes de abrir outra.

Cabeçalhos de limite

As respostas JSON trazem cabeçalhos com metadados do limite:

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

Exceder o limite retorna 429 com o código rate_limited. Aguarde antes de tentar de novo. Não há cabeçalho Retry-After.

Formato da resposta de erro

Todos os erros da API retornam um corpo JSON com um objeto error aninhado contendo um code legível por máquina e uma message legível por humanos:

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

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

Erros de validação retornam 422 com um campo details dentro do objeto de erro:

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

Já os erros de token OAuth seguem o formato RFC 6749 §5.2:

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

Códigos de erro

Repetições e espera

Recomendamos uma estratégia de espera exponencial com variação aleatória para integrações em produção:

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");
}

Não repita em erros 4xx (exceto 429): eles indicam um problema na sua requisição que não se resolve repetindo.

Formato de erro do OAuth

O endpoint de token (POST /api/oauth/token) retorna erros no formato RFC 6749: