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

- **APIs de Hub**
  - 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](./api).
- **Resolvers**
  - Son todas las URL que contienen un segmento `/resolve/` en su ruta, las cuales 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 punto de acceso ["Resolve a file"](https://huggingface-openapi.hf.space/#tag/models/get/apiresolve-cachemodelsnamespacereporevpath) 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.
- **Páginas**
  - 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.

> [!TIP]
> 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](#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

![dashboard for rate limits](https://cdn-uploads.huggingface.co/production/uploads/5dd96eb166059660ed1ee413/0pzQQyuVG3c9tWjCqrX9Y.png)

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)](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/) 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 "Límites de tasa de Hub más altos" 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 la salud de la plataforma 🤞

> [!NOTE]
> 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`](https://huggingface.co/docs/huggingface_hub/index) (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.