Rate limit

Pour garantir la stabilité et les performances de l’API DiscordTop, chaque intégration est soumise à des limites de requêtes (Rate Limits).

Lorsque ces limites sont atteintes, l’API renvoie une erreur dédiée.

Les rate limits permettent d’éviter :

• le spam involontaire,

• les boucles infinies dans les bots,

• les attaques ou abus de l’API,

• et d’assurer une expérience fiable pour tous les serveurs.

---

Comment fonctionne le Rate Limit ?

L’API utilise un système de limitation basé sur :

• le token API (api_token du serveur Discord),

• et, en absence de token, l’adresse IP de l’appelant.

Chaque token dispose d’un quota indépendant.

Par défaut :

30 requêtes / minute / api_token

Lorsque la limite est atteinte, l’API renvoie automatiquement une erreur RATE_LIMITED.

---

Erreur RATE_LIMITED

En cas de dépassement, l’API renvoie une réponse JSON standardisée :

{
  "ok": false,
  "error": "RATE_LIMITED",
  "message": "Rate limit exceeded for this API token."
}

Code HTTP renvoyé :

429 Too Many Requests

Champs renvoyés :

Champ	Description
status	Code HTTP 429
error	Message clair, adapté à la locale (fr, en, etc.)
retry_after	Temps recommandé (en secondes) avant de réessayer

---

Reset de la limite

Le compteur se réinitialise automatiquement au bout d’une minute.

Pendant ce temps, il est recommandé de :

• mettre en cache les résultats,

• réduire la fréquence des appels,

• éviter les appels simultanés,

• centraliser vos appels API dans un seul module.

---

Locale et messages d’erreur

L’API DiscordTop adapte automatiquement les messages selon la langue de l’utilisateur :

L’ordre de priorité est :

1. locale=xx (query ou body)

2. Accept-Language

3. x-locale

4. Fallback → en

Exemples :

Locale	Message
fr	"Trop de requêtes. Veuillez réessayer plus tard."
en	"Rate limit exceeded. Please try again later."

---

Bonnes pratiques

Voici quelques recommandations pour éviter d’être limité :

- Cachez la réponse si possible

Exemples :

• mémoriser la réponse pendant 2–5 secondes dans votre bot

• éviter de multiplier les appels identiques

- Ne faites pas d’appel via le front-end

Les navigateurs peuvent spam / reload plus facilement → utilisez uniquement votre backend.

- Centralisez vos appels

Évitez d’appeler l’API dans plusieurs endroits simultanément (ex. inside command + middleware + cron).

- Vérifiez toujours que l’utilisateur peut déclencher une action avant d’appeler l’API

(ex : s’il spam un bouton Discord)

- En cas d'échec à cause d’un 429, appliquez un retry after progressif

1ère tentative : attendre 1 seconde 2ème tentative : attendre 3 secondes 3ème tentative : annuler

Note : des en-têtes de suivi du taux de requêtes pourront être ajoutés dans une prochaine mise à jour de l’API.

---

Exemple de gestion simple

const res = await fetch(url);

if (res.status === 429) {
  const body = await res.json();
  console.log(body.error, "Réessayez dans", body.retry_after, "s");
  return;
}

const data = await res.json();

Notes

• Le système de rate limit peut évoluer (Redis distribué, quotas Premium, etc.).

• Des headers d’observation (X-RateLimit-Remaining, etc.) pourront être ajoutés dans une prochaine version.