Límites de tasa de Hub

Para proteger la integridad de nuestra plataforma y garantizar la disponibilidad para el mayor número posible de miembros de la comunidad de IA, aplicamos límites de tasa a todas las solicitudes realizadas al Hugging Face Hub.

Definimos diferentes límites de tasa para distintas clases de solicitudes. Distinguimos tres categorías principales:

• Hub APIs
  • p. ej. búsqueda de modelos o conjuntos de datos, creación de repositorios, gestión de usuarios, etc. Todos los puntos finales que pertenecen a esta categoría están documentados en Hub API Endpoints.
• Resolvers
  • Son todas las URL que contienen un segmento /resolve/ en su ruta, y que sirven contenido generado por usuarios desde el Hub. Concretamente, son las URL que construyen las bibliotecas de código abierto (transformers, datasets, vLLM, llama.cpp, …) o las aplicaciones de IA (LM Studio, Jan, ollama, …) para descargar archivos de modelos/conjuntos de datos desde HF.
  • Específicamente, este es el “Resolve a file” endpoint documentado en nuestra especificación OpenAPI.
  • Los Resolve requests se utilizan mucho en la comunidad y, dado que optimizamos nuestra infraestructura para servirlos con la máxima eficiencia, los límites de tasa para los Resolvers son los más altos.
• Pages
  • Todas las páginas web que alojamos en huggingface.co.
  • Por lo general, las solicitudes de navegación web las realizan personas, por lo que los límites de tasa no necesitan ser tan altos como los de los endpoints programáticos mencionados anteriormente.

Todos los valores se definen sobre ventanas de 5 minutos, lo que permite cierto nivel de “irregularidad” desde el punto de vista de una aplicación o de un desarrollador.

Si tú, tu organización o tu aplicación necesitan límites de tasa más altos, te animamos a actualizar tu cuenta a PRO, Team o Enterprise. Priorizamos las solicitudes de soporte de los clientes PRO, Team y Enterprise; consulta los límites integrados en Rate limit Tiers.

Panel de facturación

En cualquier momento, puedes consultar el estado de tu límite de tasa en la página de facturación de tu cuenta (o de tu organización): https://huggingface.co/settings/billing

En el lado derecho, verás tres medidores, uno para cada cubo de Requests.

Cada cubo muestra el número de solicitudes actuales (últimos 5 minutos) y el número de solicitudes permitidas según el plan de tu cuenta de usuario u organización.

Siempre que supere el límite en los últimos 5 minutos (la vista se actualiza en tiempo real), la barra se volverá roja.

Nota: Puedes usar el selector de contexto para cambiar fácilmente entre tu cuenta de usuario y tus organizaciones.

Cabeceras HTTP

Cuando usted o su organización alcance un límite de tasa, recibirá un error HTTP 429 Too Many Requests.

Implementamos el mecanismo descrito en el borrador de la IETF (versión 9) titulado “RateLimit HTTP header fields for HTTP” (también conocido como draft-ietf-httpapi-ratelimit-headers).

El objetivo es definir encabezados HTTP estandarizados que los servidores puedan utilizar para anunciar políticas de cuota / límite de tasa y comunicar el uso / límites actuales a los clientes para que puedan evitar ser limitados.

Precisamente, implementamos las siguientes cabeceras:

Encabezado	Propósito / Significado
RateLimit	El límite de tasa total permitido para la ventana actual. “Cuántas solicitudes (de este tipo) se le permite realizar.”
RateLimit-Policy	Contiene la propia política de límite de tasa (p. ej., “100 solicitudes por 5 minutos”). Es informativa; muestra a qué política está sujeto el cliente.

Un conjunto de ejemplos es el siguiente:

Encabezado	Ejemplo
RateLimit	"api\|pages\|resolvers";r=[remaining];t=[seconds remaining until reset]
RateLimit-Policy	"fixed window";"api\|\pages\|resolvers";q=[total allowed for window];w=[window duration in seconds]

Niveles de límite de tasa

Estos son los límites actuales de tasa (en septiembre de 2025) según su plan:

Plan	API	Resolvers	Páginas
Usuario anónimo (por dirección IP)	500 *	3,000 *	100 *
Usuario gratuito	1,000 *	5,000 *	200 *
Usuario PRO	2,500	12,000	400
Organización del equipo	3,000	20,000	400
Organización empresarial	6,000	50,000	600
Organización Enterprise Plus	10,000	100,000	1,000
Organización Enterprise Plus Con “Higher Hub Rate Limits” habilitado	100,000	500,000	10,000
Organización del Hub de la Academia	3,000	20,000	400

* Los usuarios anónimos y gratuitos están sujetos a cambios con el tiempo según el estado de la plataforma 🤞

Todas las cuotas se calculan en ventanas fijas de 5 minutos.

Nota: En el caso de las organizaciones, los límites de tasa se aplican de forma individual a cada miembro, no se comparten entre los miembros.

¿Qué pasa si me limitan la tasa de peticiones?

Primero, asegúrate de pasar siempre un HF_TOKEN y de que se propague a todas las bibliotecas o aplicaciones que descarguen recursos del Hub.

Esta es la razón número uno por la que los usuarios se ven limitados por la tasa de peticiones y es una corrección muy sencilla.

Aunque pases HF_TOKEN, si sigues limitado por la tasa de peticiones, puedes:

• distribuya sus solicitudes a lo largo de períodos de tiempo más largos
• reemplaza las llamadas a la API de Hub con llamadas a Resolver siempre que sea posible (los límites de tasa de Resolver son mucho más altos y mucho más optimizados).
• actualizar a PRO, Team o Enterprise.

Gestión inteligente de límites de velocidad con huggingface_hub

La biblioteca de Python del Hub huggingface_hub (versión 1.2.0+) incluye un manejo inteligente de reintentos para errores de límite de tasa.

Cuando se produce un error 429, el SDK analiza automáticamente la cabecera RateLimit para extraer el número exacto de segundos hasta que se restablece el límite de tasa y, a continuación, espera precisamente ese tiempo antes de reintentar. Esto se aplica a las descargas de archivos (es decir, Resolvers) y a las llamadas paginadas a la API de Hub (listar modelos, conjuntos de datos, espacios, etc.).

Recomendamos encarecidamente usar huggingface_hub para todo acceso programático al Hub para beneficiarse de este comportamiento de reintento optimizado y evitar implementar un manejo personalizado de límites de tasa.

Límites de tasa de acciones de usuario granulares

Además de esas clases principales de límites de tasa, aplicamos límites a ciertos tipos específicos de acciones de usuario, como:

• creación de repositorio
• commits del repositorio
• discusiones y comentarios
• acciones de moderación
• etc.

Actualmente no documentamos los límites de tasa para esas acciones específicas, ya que tienden a cambiar con mayor frecuencia con el tiempo. Si recibes errores de cuota, te animamos a actualizar tu cuenta a PRO, Team o Enterprise. No dudes en ponerte en contacto con nosotros a través del equipo de soporte.

Update on GitHub