> For the complete documentation index, see [llms.txt](https://docs.discordtop.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.discordtop.net/api-reference/concepts-cles/rate-limit.md).

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.discordtop.net/api-reference/concepts-cles/rate-limit.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.