# Limites de débit

> Requêtes par minute et par clé d’API selon l’offre, les en-têtes X-RateLimit, la forme d’une 429, et comment ralentir pour rester sous la limite.

Chaque clé d’API peut effectuer un nombre défini de requêtes par minute. Ce nombre dépend de l’offre de votre compte client.

## Limites par offre

| Offre | Requêtes par minute et par clé |
| --- | --- |
| Enterprise | 120 |
| Custom | Ajusté à votre volume. 600 sauf accord contraire. |
| Autres offres | Pas d’accès à l’API (`403 api_not_in_plan`) |

La limite s’applique par clé, et non par compte. Chaque requête effectuée avec une clé valide est décomptée, y compris les requêtes qui échouent, comme une `404` ou une `403 insufficient_scope`.

La fenêtre est une minute fixe. Elle commence à la première requête d’une clé et se réinitialise 60 secondes plus tard. Ce n’est pas une moyenne glissante : une rafale en début de fenêtre peut épuiser toute la minute.

Le serveur MCP a sa propre limite : 120 appels par minute et par application connectée. Voir [Serveur MCP](https://developer.hillsmusic.com/fr/mcp/overview/).

## En-têtes

Chaque réponse porte :

| En-tête | Signification |
| --- | --- |
| `X-RateLimit-Limit` | Nombre de requêtes par minute autorisées pour cette clé. |
| `X-RateLimit-Remaining` | Requêtes restantes pour la minute en cours. |

Une `429` porte en plus :

| En-tête | Signification |
| --- | --- |
| `Retry-After` | Secondes avant la réinitialisation de la fenêtre. |

`GET /ping` donne les mêmes chiffres dans son corps, sous `plan.rate` et `rate_limit` :

```bash
curl "https://api.hillsmusic.com/v1/ping" \
  -H "Authorization: Bearer $HILLS_API_KEY"
```

```json
{
  "ok": true,
  "plan": { "included": true, "plan": "enterprise", "rate": 120 },
  "rate_limit": { "limit": 120, "remaining": 119 }
}
```

## En cas de dépassement

Au-delà de la limite, l’API renvoie `429` avant même de lire le corps de la requête :

```
HTTP/2 429
Retry-After: 23
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0

{"error":"Too many requests: at most 120 a minute per key.","code":"rate_limited"}
```

Attendez `Retry-After` secondes, puis renvoyez la requête. Rien de la requête refusée n’a été traité : vous pouvez la renvoyer sans risque, écritures comprises.

`POST /ddex/validate` peut aussi renvoyer `429 busy` quand trop de tests tournent en même temps. Il ne s’agit pas de votre limite par minute. Attendez quelques secondes et réessayez.

## Temporiser en Node

```js
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export async function hills(path, init = {}) {
  for (let attempt = 1; attempt <= 5; attempt++) {
    const res = await fetch("https://api.hillsmusic.com/v1" + path, {
      ...init,
      headers: { ...init.headers, Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
    });
    if (res.status !== 429) return res;
    const wait = Number(res.headers.get("Retry-After")) || 2 ** attempt;
    await sleep(wait * 1000);
  }
  throw new Error("Still rate limited after 5 tries");
}
```

## Mieux vaut réguler son rythme

Le mieux est de ne jamais atteindre la limite. Lisez `X-RateLimit-Remaining` et ralentissez quand la valeur devient basse :

```js
let remaining = Infinity;

async function paced(path) {
  if (remaining < 5) await sleep(5000); // close to the limit: wait for the window to reset
  const res = await hills(path);
  remaining = Number(res.headers.get("X-RateLimit-Remaining") ?? Infinity);
  return res;
}
```

Avec curl dans une boucle shell, faites une pause d’une demi-seconde entre les appels pour rester sous 120 par minute :

```bash
for id in 812 813 814; do
  curl -s "https://api.hillsmusic.com/v1/releases/$id" \
    -H "Authorization: Bearer $HILLS_API_KEY"
  sleep 0.5
done
```

## Faire moins de requêtes

- **Utilisez de grandes pages.** `GET /releases?limit=100` renvoie 100 sorties en une requête au lieu de 50.
- **Ne synchronisez que les changements.** `GET /releases?updated_since=<last run>` ne renvoie que les sorties modifiées depuis.
- **Préférez les webhooks à l’interrogation répétée.** Abonnez-vous à `release.live` ou `delivery.store_status_changed` plutôt que de vérifier chaque sortie toutes les quelques minutes. Voir [Webhooks](https://developer.hillsmusic.com/fr/guides/webhooks/).
- **Interrogez les livraisons DDEX sans précipitation.** Une livraison prend de quelques secondes à quelques minutes. Interrogez `GET /ddex/{id}` toutes les 10 à 30 secondes, ou abonnez-vous à `ddex.import.imported`.
- **Mettez en cache ce qui change rarement**, comme les membres et les revenus par mois.

## Répartir la charge entre plusieurs clés

Chaque clé a sa propre limite. Utiliser une clé par système (une pour la synchronisation de votre ERP, une pour votre site web) évite qu’un traitement chargé ne prive les autres. Ne créez pas de clés supplémentaires dans le seul but de contourner la limite. Si vous avez besoin de plus, renseignez-vous auprès de votre interlocuteur HILLS Music sur l’offre Custom, dont la limite est ajustée à votre volume.

Source: https://developer.hillsmusic.com/fr/guides/rate-limits/