Limites de débit et erreurs

Limites de débit

Les limites s'appliquent par clé d'API (ou par client OAuth) et par minute. Dépasser la limite renvoie 429 Too Many Requests.

Besoin de limites plus élevées pour votre intégration ? Contactez notre équipe.

Les sessions en direct ouvertes simultanément constituent un plafond distinct, et non une limite de débit : Free 1 salle, Pro 1 par licence de présentateur, Premium 2. L'atteindre renvoie 403 avec le code session_limit. Fermez une salle depuis Studio (ou via POST /api/v1/sessions/{id}/control avec end) avant d'en ouvrir une autre.

En-têtes de limite

Les réponses JSON portent des en-têtes de métadonnées de limite :

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

Dépasser la limite renvoie 429 avec le code rate_limited. Patientez avant de réessayer. Il n'y a pas d'en-tête Retry-After.

Format des réponses d'erreur

Toutes les erreurs de l'API renvoient un corps JSON contenant un objet error imbriqué avec un code lisible par machine et un message lisible par un humain :

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

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

Les erreurs de validation renvoient 422 avec un champ details dans l'objet d'erreur :

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

Les erreurs du jeton OAuth suivent en revanche le format RFC 6749 §5.2 :

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

Codes d'erreur

Relances et temporisation

Nous recommandons une stratégie de temporisation exponentielle avec gigue pour les intégrations en production :

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

Ne relancez pas sur les erreurs 4xx (hormis 429) : elles signalent un problème dans votre requête que la relance ne résoudra pas.

Format d'erreur OAuth

Le point de terminaison de jeton (POST /api/oauth/token) renvoie les erreurs au format RFC 6749 :