Limites de débit et erreurs

Limites de débit

Chaque application peut faire 800 requêtes REST par fenêtre glissante de 60 secondes pour chaque utilisateur au nom duquel elle agit. Le quota est calculé par paire (application, utilisateur) : les requêtes faites avec le jeton d’un utilisateur n’entament pas le quota d’un autre utilisateur, et les requêtes faites avec des jetons d’application partagent un compteur distinct qui leur est propre.

Chaque réponse REST comprend ces en-têtes :

Lorsque le quota est épuisé, l’API répond 429 jusqu’à ce que la fenêtre se libère :

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Ratelimit-Limit: 800
Ratelimit-Remaining: 0
Ratelimit-Reset: 1790265642

{"error":"Too Many Requests","status":429,"message":"rate limit exceeded"}

Format des erreurs REST

Les erreurs des points de terminaison https://api.woupi.buzz/v1 utilisent cette enveloppe : error est le libellé du statut HTTP, status le code numérique et message un détail lisible.

{
  "error": "Forbidden",
  "status": 403,
  "message": "Missing scope: chat:write"
}

Messages que vous voudrez peut-être traiter explicitement :

Considérez message comme une information destinée aux développeurs : affichez votre propre texte à vos utilisateurs et décidez d’abord en fonction du code de statut.

Format des erreurs OAuth

Les points de terminaison OAuth (/oauth2/token, /oauth2/device, /oauth2/revoke) suivent plutôt la norme OAuth 2.0, avec un code error et une error_description :

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

/oauth2/validate répond 401 avec {"status":401,"message":"invalid access token"} pour un jeton invalide. La liste complète des codes d’erreur OAuth se trouve dans Authentification.

Codes de statut HTTP

Réessayer sans risque

• 429 : attendez jusqu’à Ratelimit-Reset (au moins une seconde), puis réessayez. Surveillez Ratelimit-Remaining pour ralentir avant d’atteindre la limite.
• 500 et 503 : réessayez avec un délai exponentiel et une petite variation aléatoire (par exemple 1 s, 2 s, 4 s... plafonné à 30 s), et abandonnez après quelques tentatives.
• 401 avec un jeton d’utilisateur : actualisez le jeton une fois (voir Authentification), puis réessayez. Si l’actualisation échoue, demandez à l’utilisateur d’autoriser de nouveau votre application.
• 400, 403, 404 et 409 : ne réessayez pas la même requête; corrigez-la d’abord.
• Réessayer un PATCH ou un DELETE ne pose pas de problème. Avant de réessayer un POST qui crée quelque chose (un message de clavardage, un extrait, un abonnement), vérifiez si la première tentative a réussi.

async function woupiFetch(url, options = {}, attempt = 0) {
  const res = await fetch(url, options);
  if (attempt >= 5) return res;

  if (res.status === 429) {
    const resetMs = Number(res.headers.get('Ratelimit-Reset')) * 1000;
    const waitMs = Math.max(resetMs - Date.now(), 1000);
    await new Promise((resolve) => setTimeout(resolve, waitMs));
    return woupiFetch(url, options, attempt + 1);
  }

  if (res.status >= 500) {
    const waitMs = Math.min(30000, 1000 * 2 ** attempt) + Math.random() * 250;
    await new Promise((resolve) => setTimeout(resolve, waitMs));
    return woupiFetch(url, options, attempt + 1);
  }

  return res;
}