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

# Limites de débit

> 120 requêtes par minute et par clé, et comment s'y tenir.

L'API accepte **120 requêtes par minute et par clé**. La fenêtre est fixe : le
compteur repart de zéro à chaque nouvelle minute, il ne glisse pas.

La limite s'applique **par clé**, pas par workspace. Deux clés du même
workspace disposent chacune de leur propre budget — c'est un argument de plus
pour créer une clé par usage.

## En-têtes

Toute réponse authentifiée porte l'état du compteur :

| En-tête                 | Contenu                                                          |
| ----------------------- | ---------------------------------------------------------------- |
| `X-RateLimit-Limit`     | `120`                                                            |
| `X-RateLimit-Remaining` | Requêtes restantes dans la fenêtre en cours                      |
| `Retry-After`           | **Uniquement sur un `429`** : secondes avant la fenêtre suivante |

<Note>
  Une réponse `401` ne porte pas ces en-têtes : le compteur n'est consulté
  qu'une fois la clé reconnue. Une clé invalide ne consomme donc pas votre
  budget.
</Note>

## Dépassement

Au-delà de 120 requêtes, l'API répond `429` :

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
```

```json theme={null}
{
  "statusCode": 429,
  "message": "Limite de 120 requêtes par minute atteinte.",
  "error": "TOO_MANY_REQUESTS",
  "path": "/v1/companies?limit=200",
  "timestamp": "2026-08-25T09:14:02.518Z"
}
```

Attendez le délai indiqué par `Retry-After` puis rejouez la requête. Elle
n'a produit aucun effet : l'API est en lecture seule, un `429` ne laisse rien
derrière lui.

## Respecter la limite

```js theme={null}
async function appeler(url, cle) {
  for (let tentative = 0; tentative < 5; tentative++) {
    const res = await fetch(url, { headers: { Authorization: `Bearer ${cle}` } });

    if (res.status !== 429) return res;

    // On suit `Retry-After` plutôt qu'un délai deviné : le serveur sait
    // exactement quand la fenêtre se rouvre, le client non.
    const attente = Number(res.headers.get("Retry-After") ?? 60);
    await new Promise((r) => setTimeout(r, attente * 1000));
  }
  throw new Error("Limite de débit toujours atteinte après 5 tentatives.");
}
```

<Warning>
  Ne remplacez pas `Retry-After` par un back-off exponentiel maison. Sur une
  fenêtre fixe, un back-off qui double à l'aveugle attend systématiquement plus
  longtemps qu'il ne faut, et plusieurs clients repartent en même temps à la
  réouverture.
</Warning>

## Rester loin de la limite

* Paginez à `limit=200` plutôt qu'à 50 : quatre fois moins de requêtes pour le
  même volume.
* Utilisez `since` pour ne relire que ce qui a bougé.
* Ne sondez pas l'API en boucle courte. Les données bougent au rythme des
  visites de votre site : un passage toutes les cinq à quinze minutes suffit
  très largement, même pour une remontée « temps réel » perçue.