Rate Limits

Jeder API-Schlüssel darf eine festgelegte Zahl von Anfragen pro Minute senden. Die Zahl ergibt sich aus dem Tarif Ihres Kundenkontos.

Limits pro Tarif

Das Limit gilt pro Schlüssel, nicht pro Konto. Jede Anfrage mit einem gültigen Schlüssel zählt, auch fehlgeschlagene wie ein 404 oder ein 403 insufficient_scope.

Das Zeitfenster ist eine feste Minute. Es beginnt mit der ersten Anfrage eines Schlüssels und wird 60 Sekunden später zurückgesetzt. Es ist kein gleitender Durchschnitt: Ein Burst zu Beginn eines Fensters kann die ganze Minute aufbrauchen.

Der MCP-Server hat ein eigenes Limit: 120 Aufrufe pro Minute und verbundener App. Siehe MCP-Server.

Header

Jede Antwort enthält:

Eine 429 enthält zusätzlich:

GET /ping zeigt dieselben Zahlen im Body, unter plan.rate und 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 }
}

Wenn Sie das Limit überschreiten

Über dem Limit antwortet die API mit 429, bevor sie den Request-Body liest:

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

Warten Sie Retry-After Sekunden und senden Sie die Anfrage dann erneut. Von der abgelehnten Anfrage wurde nichts verarbeitet. Sie können sie also gefahrlos erneut senden, auch Schreibzugriffe.

POST /ddex/validate kann außerdem mit 429 busy antworten, wenn zu viele Tests gleichzeitig laufen. Das ist nicht Ihr Minutenlimit. Warten Sie ein paar Sekunden und versuchen Sie es noch einmal.

Backoff in 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");
}

Besser: das Tempo selbst steuern

Am besten erreichen Sie das Limit gar nicht erst. Lesen Sie X-RateLimit-Remaining und werden Sie langsamer, wenn der Wert niedrig wird:

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;
}

Mit curl in einer Shell-Schleife warten Sie zwischen den Aufrufen eine halbe Sekunde, um unter 120 pro Minute zu bleiben:

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

Weniger Anfragen senden

• Mit großen Seiten blättern. GET /releases?limit=100 liefert 100 Releases mit einer Anfrage statt 50.
• Nur Änderungen synchronisieren. GET /releases?updated_since=<last run> liefert nur Releases, die sich seitdem geändert haben.
• Webhooks statt Polling. Abonnieren Sie release.live oder delivery.store_status_changed, statt jedes Release alle paar Minuten abzufragen. Siehe Webhooks.
• DDEX-Auslieferungen gemächlich abfragen. Eine Auslieferung dauert Sekunden bis Minuten. Fragen Sie GET /ddex/{id} alle 10–30 Sekunden ab oder abonnieren Sie ddex.import.imported.
• Selten Veränderliches cachen, etwa Mitglieder und Erlöse nach Monat.

Last auf mehrere Schlüssel verteilen

Jeder Schlüssel hat sein eigenes Limit. Mit einem Schlüssel pro System (einer für Ihren ERP-Abgleich, einer für Ihre Website) bremst ein ausgelasteter Job die anderen nicht aus. Erstellen Sie aber keine zusätzlichen Schlüssel, nur um das Limit zu umgehen. Brauchen Sie mehr, fragen Sie Ihren Ansprechpartner bei HILLS Music nach dem Tarif Custom, bei dem das Limit auf Ihr Volumen abgestimmt wird.