Limites de taxa do Hub

Para proteger a integridade da nossa plataforma e garantir a disponibilidade para o maior número possível de membros da comunidade de IA, aplicamos limites de taxa a todas as solicitações feitas ao Hugging Face Hub.

Definimos limites de taxa diferentes para classes distintas de solicitações. Distinguimos três principais categorias:

• Hub APIs
  • por exemplo, busca de modelos ou conjuntos de dados, criação de repositórios, gerenciamento de usuários, etc. Todos os endpoints que pertencem a esse grupo estão documentados em Hub API Endpoints.
• Resolvers
  • Todos eles são URLs que contêm um segmento /resolve/ em seu caminho, que servem conteúdo gerado por usuários do Hub. Concretamente, são as URLs construídas por bibliotecas de código aberto (transformers, datasets, vLLM, llama.cpp, …) ou aplicações de IA (LM Studio, Jan, ollama, …) para baixar arquivos de modelo/conjunto de dados do HF.
  • Especificamente, este é o endpoint “Resolve a file” documentado em nossa especificação OpenAPI.
  • As solicitações de Resolve são amplamente utilizadas pela comunidade e, como otimizamos nossa infraestrutura para atendê-las com máxima eficiência, os limites de taxa para Resolvers são os mais altos.
• Pages
  • Todas as páginas da Web que hospedamos no huggingface.co.
  • Normalmente, as solicitações de navegação na Web são feitas por humanos, portanto, os limites de taxa não precisam ser tão altos quanto os endpoints programáticos mencionados acima.

Todos os valores são definidos em janelas de 5 minutos, o que permite um certo nível de “variação de carga” do ponto de vista de uma aplicação ou de um desenvolvedor.

Se você, sua organização ou seu aplicativo necessitam de limites de taxa mais altos, incentivamos você a fazer o upgrade da sua conta para PRO, Team ou Enterprise. Damos prioridade a solicitações de suporte de clientes PRO, Team e Enterprise – veja os limites integrados em Rate limit Tiers.

Painel de faturamento

A qualquer momento, você pode verificar o status do seu limite de taxa na página de Faturamento (sua ou da sua organização): https://huggingface.co/settings/billing

No lado direito, você verá três medidores, um para cada bucket de Requests.

Cada bucket apresenta o número de solicitações atuais (últimos 5 minutos) e o número de solicitações permitidas com base no plano da sua conta de usuário ou organização.

Sempre que você exceder o limite nos últimos 5 minutos (a visualização é atualizada em tempo real), a barra ficará vermelha.

Observação: você pode usar o seletor de contexto para alternar facilmente entre sua conta de usuário e suas organizações.

Cabeçalhos HTTP

Sempre que você ou sua organização atingir um limite de taxa, receberá um erro HTTP 429 Too Many Requests.

Implementamos o mecanismo descrito no rascunho da IETF (Versão 9) intitulado “RateLimit HTTP header fields for HTTP” (também conhecido como draft-ietf-httpapi-ratelimit-headers).

O objetivo é definir cabeçalhos HTTP padronizados que os servidores podem usar para anunciar políticas de cota / limite de taxa e comunicar o uso atual / limites aos clientes, para que eles possam evitar ser limitados.

Precisamente, implementamos os seguintes cabeçalhos:

Cabeçalho	Propósito / Significado
RateLimit	O limite de taxa total permitido para a janela atual. “Quantas solicitações (deste tipo) você está autorizado a executar.”
RateLimit-Policy	Carrega a própria política de limite de taxa (por exemplo, “100 requisições a cada 5 minutos”). É informativo; mostra qual política o cliente está sujeito.

Um conjunto de exemplos é o seguinte:

Cabeçalho	Exemplo
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]

Níveis de limite de taxa

Aqui estão os limites de taxa atuais (em setembro de 2025) com base no seu plano:

Plano	API	Resolvers	Páginas
Usuário anônimo (por endereço IP)	500 *	3,000 *	100 *
Usuário gratuito	1,000 *	5,000 *	200 *
Usuário PRO	2,500	12,000	400
Organização da equipe	3,000	20,000	400
Organização empresarial	6,000	50,000	600
Organização Enterprise Plus	10,000	100,000	1,000
Organização Enterprise Plus Com “Limites de taxa do Hub mais altos” ativado	100,000	500,000	10,000
Organização Academia Hub	3,000	20,000	400

* Usuários anônimos e gratuitos estão sujeitos a alterações ao longo do tempo, dependendo da saúde da plataforma 🤞

Todas as cotas são calculadas em janelas fixas de 5 minutos.

Observação: Para organizações, os limites de taxa são aplicados individualmente a cada membro, e não compartilhados entre os membros.

E se eu for limitado por taxa

Primeiro, certifique-se de sempre passar um HF_TOKEN, e de que ele seja repassado para todas as bibliotecas ou aplicações que baixam conteúdo do Hub.

Este é o principal motivo pelo qual os usuários atingem o limite de requisições e é uma correção muito simples.

Mesmo passando HF_TOKEN, se você ainda estiver limitado por taxa, você pode:

• distribua suas solicitações ao longo de períodos de tempo mais longos
• substitua as chamadas da API do Hub por chamadas do Resolver, sempre que possível (os limites de taxa do Resolver são muito maiores e muito mais otimizados).
• atualize para PRO, Team ou Enterprise.

Tratamento inteligente de limites de taxa com huggingface_hub

A Biblioteca Python do Hub huggingface_hub (versão 1.2.0+) inclui tratamento inteligente de novas tentativas para erros de limite de taxa.

Quando um erro 429 ocorre, o SDK analisa automaticamente o cabeçalho RateLimit para extrair o número exato de segundos até a redefinição do limite de taxa e, em seguida, aguarda exatamente esse período antes de tentar novamente. Isso se aplica a downloads de arquivos (ou seja, Resolvers) e a chamadas paginadas da API do Hub (listar modelos, datasets, spaces, etc.).

Recomendamos fortemente o uso de huggingface_hub para todo acesso programático ao Hub para se beneficiar desse comportamento otimizado de nova tentativa e evitar a implementação de tratamento personalizado de limites de taxa.

Limites de taxa de ações de usuário granulares

Além dessas principais classes de limites de taxa, aplicamos limites a certos tipos específicos de ações do usuário, como:

• criação de repositório
• commits do repositório
• discussões e comentários
• ações de moderação
• etc.

No momento, não documentamos os limites de taxa para essas ações específicas, pois eles tendem a mudar com mais frequência ao longo do tempo. Se você receber erros de cota, recomendamos que você atualize sua conta para PRO, Team ou Enterprise. Sinta-se à vontade para entrar em contato conosco por meio da equipe de suporte.

Update on GitHub