# Rate limit

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 :

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

Code HTTP renvoyé :

```
429 Too Many Requests
```

#### Champs renvoyés :

<table><thead><tr><th width="213">Champ</th><th>Description</th></tr></thead><tbody><tr><td><code>status</code></td><td>Code HTTP 429</td></tr><tr><td><code>error</code></td><td>Message clair, adapté à la locale (<code>fr</code>, <code>en</code>, etc.)</td></tr><tr><td><code>retry_after</code></td><td>Temps recommandé (en secondes) avant de réessayer</td></tr></tbody></table>

***

## 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 :

<table><thead><tr><th width="190">Locale</th><th>Message</th></tr></thead><tbody><tr><td><code>fr</code></td><td><code>"Trop de requêtes. Veuillez réessayer plus tard."</code></td></tr><tr><td><code>en</code></td><td><code>"Rate limit exceeded. Please try again later."</code></td></tr></tbody></table>

***

## 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

{% hint style="info" %}
*Note : des en-têtes de suivi du taux de requêtes pourront être ajoutés dans une prochaine mise à jour de l’API.*
{% endhint %}

***

## Exemple de gestion simple

```ts
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.