Limites de débit

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

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.

En-têtes

Chaque réponse porte :

Une 429 porte en plus :

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

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

{
  "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

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 :

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 :

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