Límites y cuotas

Tu cuenta tiene dos límites independientes, fijados por tu plan: una cuota de requests (cuánto llamas sobre una ventana) y un límite de ráfaga (qué tan rápido llamas en el momento). Esta página cubre ambos, los headers que enviamos, cómo se ve cada 429 y cómo leer tu propio uso.

Cuotas por plan

Los límites son valores de lanzamiento y pueden cambiar antes de la disponibilidad general. Los precios y la comparación de planes están en la sección de precios.

Una sola cuota por cuenta

La cuota es tuya, no de una key en particular. Todas tus keys consumen de la misma cuota, y un request hecha con cualquiera de ellas cuenta contra el mismo total. Crear una segunda key te da una segunda credencial, nunca una segunda cuota.

Puedes tener hasta 5 keys a la vez. Las keys existen para separar entornos y rotar un secreto sin caídas: usa una por app o por entorno, y revoca las que ya no necesites.

Cuándo se reinicia la ventana

Las dos ventanas se comportan distinto, y la diferencia importa si estás ajustando el ritmo de un proceso.

• Gratuito (Taster): 24 horas móviles. Tu uso es lo que gastaste en las últimas 24 horas, medido por horas. Nada se reinicia a medianoche: la cuota se libera de a poco, a medida que cada hora sale de la ventana. Si gastas todo a las 15:00, vuelves a estar libre alrededor de las 15:00 del día siguiente, no a las 00:00.
• De pago: tu período de facturación. El uso cuenta desde el inicio del período actual y se reinicia al renovar. Subir de un plan de pago a otro eleva el techo de inmediato, sin mover la fecha de renovación ni borrar lo ya gastado.

RateLimit-Reset siempre indica cuándo se libera cuota: el inicio de la hora siguiente en el plan gratuito, la próxima renovación en uno de pago.

Acceso del plan gratuito

Además de la cuota de volumen, el plan gratuito Taster tiene tres límites estructurales. Está pensado para consultar, no para descargar el catálogo en bloque. Los planes de pago levantan los tres.

• Listado mediante búsqueda. Un endpoint de lista requiere una búsqueda ?q= (los filtros y el orden se combinan encima), o consultas un único registro con GET /v1/{resource}/{id}. Una lista vacía o solo con filtros devuelve 403 /problems/enumeration-forbidden.
• Profundidad de resultados. Los resultados de búsqueda se limitan a aproximadamente los primeros 1000; paginar más allá devuelve 403 /problems/result-depth-exceeded.
• Un solo mercado. Sirves un mercado (país) a tu elección. Defínelo en tu panel o con PUT /v1/market; hasta que lo hagas, las peticiones a foods devuelven 403 /problems/market-not-selected. Una vez definido, foods queda acotado a ese mercado. El mercado pertenece a tu cuenta, así que todas tus claves sirven el mismo. Ver Elegir tu mercado.

Headers RateLimit

Cada respuesta medida lleva tu estado actual, para que nunca tengas que adivinar. Enviamos tanto los headers IETF RateLimit-* como los alias X-RateLimit-*, ampliamente reconocidos:

Qué cuenta como request

Un 304 Not Modified cuenta. Cuando revalidas una página cacheada con If-None-Match (ver Consultas y modelo de datos), el request igual llegó a la API, así que se mide y se limita igual que un 200. Al revalidar ahorras ancho de banda y tiempo, no cuota.

Una respuesta que tu propio cliente sirve desde su caché nunca nos llega, así que no hay nada que contar. Esa es la única lectura gratis.

Cuando llegas al límite

Al alcanzar o superar la cuota, los requests devuelven 429 con un header Retry-After (segundos hasta el reinicio). El request bloqueado no se cuenta en tu contra. Ambos 429 traen los mismos tres miembros de extensión (limit, window y retry_after), así que puedes esperar a partir del cuerpo aunque no leas los headers.

{
  "type": "/problems/quota-exceeded",
  "title": "Quota exceeded",
  "status": 429,
  "limit": 250,
  "window": "daily",
  "retry_after": 1623,
  "detail": "Request quota of 250 per day exceeded. Retry once the current window resets.",
  "doc_url": "https://api.noms.sh/docs#tag/quota-exceeded"
}

Manéjalo esperando hasta Retry-After:

const res = await fetch(url, { headers: { "X-API-Key": process.env.NOMS_KEY } });
if (res.status === 429) {
  const wait = Number(res.headers.get("Retry-After")) * 1000;
  await new Promise((r) => setTimeout(r, wait));
  // ...luego reintenta
}

Límites de ráfaga

Aparte de la cuota, cada plan tiene un límite de ráfaga que limita qué tan rápido llamas, no cuánto en total. Puedes estar muy por debajo de tu cuota y aun así pedirte que vayas más despacio si disparas requests demasiado rápido en una ventana corta.

Piénsalo como un cubo de fichas: cada request gasta una, y las fichas se reponen a la tasa sostenida. Una ráfaga de llamadas tras un momento de calma está bien; para eso está la reserva de ráfaga. Un bucle incesante queda limitado a la tasa sostenida una vez agotada la ráfaga. Como la cuota, el cubo es por cuenta: llamar con varias keys a la vez gasta del mismo cubo, no multiplica tu tasa.

Si vas demasiado rápido, los requests devuelven 429 con un header Retry-After (normalmente uno o dos segundos) y un type de problema distinto al del 429 de cuota:

{
  "type": "/problems/rate-limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "limit": 1.0,
  "window": "second",
  "retry_after": 1,
  "detail": "Burst rate limit of 1 requests per second exceeded. Slow down and retry after the Retry-After interval.",
  "doc_url": "https://api.noms.sh/docs#tag/rate-limited"
}

Manéjalo igual que un 429 de cuota: espera hasta Retry-After, con el mismo fragmento de arriba. Ramifica según el campo type si quieres un comportamiento distinto. A diferencia del 429 de cuota, un 429 de ráfaga lleva solo Retry-After, no los headers RateLimit-*.

Consulta tu uso

Lee el conteo de la ventana actual de tu cuenta en cualquier momento con GET /v1/usage. No es medido, así que sigue accesible incluso cuando estás sobre la cuota:

curl https://api.noms.sh/v1/usage \
  -H "Authorization: Bearer $NOMS_KEY"

Tu panel muestra el mismo total, más un desglose por key de dónde se fue.

Próximos pasos

• Soporte: qué enviarnos cuando algo sigue sin cuadrar.