# Limites de requisições

> Requisições por minuto por chave de API em cada plano, os headers X-RateLimit, como é um 429 e como recuar e ficar abaixo do limite.

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

| Plano | Requisições por minuto, por chave |
| --- | --- |
| Enterprise | 120 |
| Custom | Definido conforme o seu volume. 600, salvo acordo em contrário. |
| Outros planos | Sem acesso à API (`403 api_not_in_plan`) |

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](https://developer.hillsmusic.com/pt/mcp/overview/).

## Headers

Toda resposta traz:

| Header | Significado |
| --- | --- |
| `X-RateLimit-Limit` | Requisições por minuto que esta chave pode fazer. |
| `X-RateLimit-Remaining` | Requisições restantes no minuto atual. |

Um `429` traz também:

| Header | Significado |
| --- | --- |
| `Retry-After` | Segundos até a janela ser zerada. |

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

## 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

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

## Melhor ainda: controle o ritmo

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

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

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

```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
```

## 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](https://developer.hillsmusic.com/pt/guides/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.

Fonte: https://developer.hillsmusic.com/pt/guides/rate-limits/