> ## Documentation Index
> Fetch the complete documentation index at: https://docs-api.maketou.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Limites de fréquence

> Comprenez les limites de requêtes de l'API Maketou et gérez les réponses 429.

Pour garantir la stabilité et la disponibilité de l'API pour l'ensemble des marchands, l'API publique de Maketou applique des **limites de fréquence (rate limiting)** sur les requêtes.

## Les limites

Les limites s'appliquent **par clé API** selon deux fenêtres complémentaires, auxquelles s'ajoute une protection par adresse IP :

| Limite               | Périmètre      | Seuil        | Fenêtre     |
| -------------------- | -------------- | ------------ | ----------- |
| Rafale (burst)       | Par clé API    | 60 requêtes  | 10 secondes |
| Soutenue (sustained) | Par clé API    | 600 requêtes | 60 secondes |
| Protection IP        | Par adresse IP | 300 requêtes | 60 secondes |

Une requête est rejetée dès qu'**une seule** de ces limites est atteinte. La limite de rafale protège contre les pics de requêtes ; la limite soutenue plafonne le volume sur une minute.

## Headers de réponse

Chaque réponse de l'API publique inclut des headers vous permettant de suivre votre consommation :

| Header                  | Description                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------ |
| `X-RateLimit-Limit`     | Nombre maximal de requêtes autorisées sur la fenêtre                                       |
| `X-RateLimit-Remaining` | Nombre de requêtes restantes sur la fenêtre en cours                                       |
| `X-RateLimit-Reset`     | Date de réinitialisation de la fenêtre (timestamp Unix, en secondes)                       |
| `Retry-After`           | Présent uniquement sur une réponse `429`. Nombre de secondes à attendre avant de réessayer |

## Réponse en cas de dépassement

Lorsqu'une limite est dépassée, l'API répond avec le code HTTP `429 Too Many Requests` :

```json theme={null}
{
  "code": "RATE_LIMITED",
  "message": "Too many requests. Please retry later."
}
```

La réponse contient le header `Retry-After` indiquant le délai (en secondes) à respecter avant de renvoyer une requête.

## Bonnes pratiques

* **Respectez le header `Retry-After`** : en cas de `429`, attendez le délai indiqué avant de réessayer.
* **Mettez en place un backoff** : espacez vos tentatives plutôt que de boucler immédiatement après un `429`.
* **Surveillez `X-RateLimit-Remaining`** : anticipez l'atteinte de la limite pour lisser votre trafic.
* **Évitez le polling agressif** : pour vérifier le statut d'un panier, espacez vos appels (par exemple, toutes les quelques secondes) plutôt que de manière continue.