Limites de débit du Hub

Afin de préserver l’intégrité de notre plateforme et de garantir sa disponibilité au plus grand nombre de membres de la communauté de l’IA, nous appliquons des limites de débit à toutes les requêtes effectuées vers le Hugging Face Hub.

Nous définissons des limites de débit différentes pour des classes de requêtes distinctes. Nous distinguons trois principaux groupes :

• Hub APIs
  • par exemple, la recherche de modèles ou de jeux de données, la création de dépôts, la gestion des utilisateurs, etc. Tous les points de terminaison appartenant à cette catégorie sont documentés dans Hub API Endpoints.
• Resolvers
  • Ce sont toutes les URL qui contiennent un segment /resolve/ dans leur chemin et qui servent du contenu généré par les utilisateurs depuis le Hub. Concrètement, il s’agit des URL construites par des bibliothèques open source (transformers, datasets, vLLM, llama.cpp, …) ou des applications IA (LM Studio, Jan, ollama, …) pour télécharger des fichiers de modèles/datasets depuis HF.
  • Plus précisément, il s'agit de l'endpoint « Resolve a file » documenté dans notre spécification OpenAPI.
  • Les requêtes Resolve sont très utilisées par la communauté, et comme nous optimisons notre infrastructure pour les servir avec une efficacité maximale, les limites de débit pour les Resolvers sont les plus élevées.
• Pages
  • Toutes les pages Web que nous hébergeons sur huggingface.co.
  • Les requêtes de navigation Web sont généralement effectuées par des humains, les limites de débit n’ont donc pas besoin d’être aussi élevées que pour les endpoints programmatiques mentionnés précédemment.

Toutes les valeurs sont définies sur des fenêtres de 5 minutes, ce qui permet un certain niveau de « burstiness » du point de vue d’une application ou d’un développeur.

Si vous, votre organisation ou votre application avez besoin de limites de débit plus élevées, nous vous encourageons à passer votre compte au niveau PRO, Team ou Enterprise. Nous donnons la priorité aux demandes de support des clients PRO, Team et Enterprise – consultez les limites intégrées dans Rate limit Tiers.

Tableau de bord de facturation

À tout moment, vous pouvez vérifier l’état de votre limite de débit sur la page Facturation de votre compte (ou de votre organisation) : https://huggingface.co/settings/billing

À droite, vous verrez trois jauges, une pour chaque bucket de Requests.

Chaque bucket présente le nombre de requêtes actuelles (5 dernières minutes) et le nombre de requêtes autorisées en fonction de votre plan d’abonnement utilisateur ou organisation.

Chaque fois que vous dépassez la limite au cours des 5 dernières minutes (la vue est mise à jour en temps réel), la barre passe au rouge.

Note : Vous pouvez utiliser le sélecteur de contexte pour passer facilement de votre compte utilisateur à vos organisations.

En-têtes HTTP

Chaque fois que vous ou votre organisation atteignez une limite de débit, vous recevez une erreur HTTP 429 Too Many Requests.

Nous implémentons le mécanisme décrit dans le brouillon IETF (version 9) intitulé « RateLimit HTTP header fields for HTTP » (également connu sous le nom de draft-ietf-httpapi-ratelimit-headers).

L’objectif est de définir des en-têtes HTTP standardisés que les serveurs peuvent utiliser pour annoncer leurs politiques de quota / de limitation de débit et communiquer aux clients l’utilisation actuelle / les limites, afin que ceux-ci puissent éviter d’être bridés.

Plus précisément, nous implémentons les en-têtes suivants :

En-tête	Objectif / Signification
RateLimit	Limite de débit totale autorisée pour la fenêtre actuelle. « Nombre de requêtes (de ce type) que vous êtes autorisé à effectuer. »
RateLimit-Policy	Contient la politique de limitation de débit elle-même (par exemple « 100 requêtes par 5 minutes »). Elle est informative ; elle indique la politique à laquelle le client est soumis.

Voici un ensemble d'exemples :

En-tête	Exemple
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]

Niveaux de limitation de débit

Voici les limites de débit actuelles (en septembre 2025) en fonction de votre plan :

Plan	API	Résolveurs	Pages
Utilisateur anonyme (par adresse IP)	500 *	3,000 *	100 *
Utilisateur gratuit	1,000 *	5,000 *	200 *
PRO utilisateur	2,500	12,000	400
Organisation de l'équipe	3,000	20,000	400
Organisation d'entreprise	6,000	50,000	600
Organisation Enterprise Plus	10,000	100,000	1,000
Organisation Enterprise Plus Avec « Limites de débit Hub plus élevées » activées	100,000	500,000	10,000
Organisation Academia Hub	3,000	20,000	400

* Les utilisateurs Anonymes et Free sont susceptibles d'évoluer au fil du temps en fonction de la santé de la plateforme 🤞

Tous les quotas sont calculés sur des fenêtres fixes de 5 minutes.

Note : Pour les organisations, les limites de débit sont appliquées individuellement à chaque membre, et non partagées entre les membres.

Que se passe-t-il si je suis limité par le taux de requêtes

Premièrement, assurez-vous de toujours transmettre un HF_TOKEN, et qu’il est transmis en aval à toutes les bibliothèques ou applications qui téléchargent des éléments depuis le Hub.

C'est la première raison pour laquelle les utilisateurs se font limiter en débit, et c'est une correction très simple.

Même après avoir passé HF_TOKEN, si vous êtes toujours limité en débit, vous pouvez :

• répartissez vos requêtes sur des périodes plus longues
• remplacez les appels à l'API du Hub par des appels à Resolver, chaque fois que possible (les limites de débit de Resolver sont beaucoup plus élevées et beaucoup plus optimisées).
• passer à PRO, Team ou Enterprise.

Gestion intelligente des limites de débit avec huggingface_hub

La bibliothèque Python du Hub huggingface_hub (version 1.2.0+) inclut une gestion intelligente des nouvelles tentatives pour les erreurs de limite de débit.

Lorsqu’une erreur 429 se produit, le SDK analyse automatiquement l’en-tête RateLimit pour extraire le nombre exact de secondes avant la réinitialisation de la limite de débit, puis attend précisément cette durée avant de réessayer. Cela s’applique aux téléchargements de fichiers (c’est-à-dire les Resolvers) et aux appels paginés de l’API Hub (liste des modèles, des jeux de données, des espaces, etc.).

Nous recommandons vivement d’utiliser huggingface_hub pour tout accès programmatique au Hub afin de bénéficier de ce comportement de nouvelle tentative optimisé et d’éviter d’implémenter une gestion personnalisée des limites de débit.

Limites de débit des actions utilisateur granulaires

En plus de ces principales catégories de limites de débit, nous appliquons des limites à certains types spécifiques d’actions utilisateur, comme :

• création de dépôt
• commits du dépôt
• discussions et commentaires
• actions de modération
• etc.

Nous ne documentons actuellement pas les limites de débit pour ces actions spécifiques, car elles ont tendance à changer plus fréquemment au fil du temps. Si vous rencontrez des erreurs de quota, nous vous encourageons à passer votre compte au niveau PRO, Team ou Enterprise. N’hésitez pas à nous contacter via l’équipe de support.

Update on GitHub