# Límites de solicitudes

> Solicitudes por minuto y clave de API en cada plan, las cabeceras X-RateLimit, cómo es un 429 y cómo esperar y mantenerte por debajo del límite.

Cada clave de API puede hacer un número fijo de solicitudes por minuto. Ese número depende del plan de tu cuenta de socio.

## Límites por plan

| Plan | Solicitudes por minuto, por clave |
| --- | --- |
| Enterprise | 120 |
| Custom | Según tu volumen. 600 salvo otro acuerdo. |
| Otros planes | Sin acceso a la API (`403 api_not_in_plan`) |

El límite es por clave, no por cuenta. Cuenta cada solicitud hecha con una clave válida, incluidas las que fallan, como un `404` o un `403 insufficient_scope`.

La ventana es un minuto fijo. Empieza con la primera solicitud de una clave y se reinicia 60 segundos después. No es una media móvil, así que una ráfaga al principio de una ventana puede agotar el minuto entero.

El servidor MCP tiene su propio límite: 120 llamadas por minuto por aplicación conectada. Consulta [Servidor MCP](https://developer.hillsmusic.com/es/mcp/overview/).

## Cabeceras

Todas las respuestas llevan:

| Cabecera | Significado |
| --- | --- |
| `X-RateLimit-Limit` | Solicitudes por minuto que puede hacer esta clave. |
| `X-RateLimit-Remaining` | Solicitudes que quedan en el minuto en curso. |

Un `429` lleva además:

| Cabecera | Significado |
| --- | --- |
| `Retry-After` | Segundos que faltan para que se reinicie la ventana. |

`GET /ping` muestra las mismas cifras en su cuerpo, en `plan.rate` y `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 }
}
```

## Cuando superas el límite

Por encima del límite, la API responde `429` antes de leer el cuerpo de la solicitud:

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

Espera los segundos de `Retry-After` y vuelve a enviar la solicitud. No se procesó nada de la solicitud rechazada, así que puedes reenviarla sin riesgo, también si es una escritura.

`POST /ddex/validate` también puede responder `429 busy` cuando hay demasiadas pruebas en curso a la vez. No es tu límite por minuto. Espera unos segundos y vuelve a intentarlo.

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

## Mejor, regula el ritmo

Lo ideal es no llegar nunca al límite. Lee `X-RateLimit-Remaining` y frena cuando quede poco:

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

Con curl en un bucle de shell, espera medio segundo entre llamadas para no pasar 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
```

## Haz menos solicitudes

- **Pagina con páginas grandes.** `GET /releases?limit=100` da 100 lanzamientos en una sola solicitud en lugar de 50.
- **Sincroniza solo los cambios.** `GET /releases?updated_since=<last run>` devuelve solo los lanzamientos modificados desde entonces.
- **Usa webhooks en lugar de sondear.** Suscríbete a `release.live` o `delivery.store_status_changed` en lugar de comprobar cada lanzamiento cada pocos minutos. Consulta [Webhooks](https://developer.hillsmusic.com/es/guides/webhooks/).
- **Consulta las entregas DDEX sin prisa.** Una entrega tarda de segundos a minutos. Consulta `GET /ddex/{id}` cada 10–30 segundos, o suscríbete a `ddex.import.imported`.
- **Guarda en caché lo que cambia poco**, como los miembros y los ingresos por mes.

## Repartir la carga entre claves

Cada clave tiene su propio límite. Usar una clave por sistema (una para la sincronización con tu ERP, otra para tu web) evita que un proceso muy activo deje sin margen a los demás. No crees claves de más solo para sortear el límite. Si necesitas más, pregunta a tu contacto en HILLS Music por el plan Custom, en el que el límite se fija según tu volumen.

Fuente: https://developer.hillsmusic.com/es/guides/rate-limits/