Limites de requisições

Cada chave de API pode fazer um número definido de requisições por minuto. Esse número vem do plano da sua conta de cliente.

Limites por plano

O limite é por chave, não por conta. Toda requisição feita com uma chave válida conta, inclusive as que falham, como um 404 ou um 403 insufficient_scope.

A janela é um minuto fixo. Ela começa com a primeira requisição da chave e é zerada 60 segundos depois. Não é uma média móvel, então um pico no início da janela pode consumir o minuto inteiro.

O servidor MCP tem o seu próprio limite: 120 chamadas por minuto por app conectado. Veja Servidor MCP.

Headers

Toda resposta traz:

Um 429 traz também:

GET /ping mostra os mesmos números no corpo, em plan.rate e 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 }
}

Quando você passa do limite

Acima do limite, a API responde 429 antes de ler o corpo da requisição:

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

Aguarde Retry-After segundos e envie a requisição de novo. Nada da requisição recusada foi processado, então é seguro reenviá-la, inclusive no caso de escritas.

POST /ddex/validate também pode responder 429 busy quando há testes demais rodando ao mesmo tempo. Isso não é o seu limite por minuto. Aguarde alguns segundos e tente de novo.

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

Melhor ainda: controle o ritmo

O ideal é nem chegar ao limite. Leia X-RateLimit-Remaining e diminua o ritmo quando o valor estiver baixo:

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

Com curl em um loop de shell, espere meio segundo entre as chamadas para ficar abaixo de 120 por minuto:

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

Faça menos requisições

• Use páginas grandes. GET /releases?limit=100 traz 100 lançamentos em uma requisição, em vez de 50.
• Sincronize só as mudanças. GET /releases?updated_since=<last run> retorna apenas os lançamentos alterados desde então.
• Use webhooks em vez de polling. Assine release.live ou delivery.store_status_changed em vez de consultar cada lançamento a cada poucos minutos. Veja Webhooks.
• Consulte as entregas DDEX sem pressa. Uma entrega leva de segundos a minutos. Consulte GET /ddex/{id} a cada 10 a 30 segundos, ou assine ddex.import.imported.
• Faça cache do que muda pouco, como membros e ganhos por mês.

Distribuir a carga entre chaves

Cada chave tem o seu próprio limite. Usar uma chave por sistema (uma para a sincronização do ERP, outra para o site) evita que uma rotina pesada esgote as demais. Não crie chaves extras só para contornar o limite. Se precisar de mais, pergunte ao seu contato na HILLS Music sobre o plano Custom, em que o limite é definido conforme o seu volume.