Límites de solicitudes

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

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.

Cabeceras

Todas las respuestas llevan:

Un 429 lleva además:

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

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

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:

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:

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