Error messages

429 Client Error: Too Many Requests for url

429 Client Error: Too Many Requests for url

This is how the Hub's rate limit looked in a log posted to one of Meta's research repos in October 2025, from an older huggingface_hub:

429 Client Error: Too Many Requests for url: https://huggingface.co/api/datasets/meta-agents-research-environments/gaia2_filesystem/paths-info/main (Request ID: Root=1-68f932c8-11103b813785183521c6fac0;167b8b9a-d5f7-40e8-ae5f-54eba22711d3)

We had to rate limit you, you hit the quota of 3000 api requests per 5 minutes period. Upgrade to higher plan to get higher limits (current: team). See https://huggingface.co/docs/hub/rate-limits

The first line is the library's. The second is the Hub's own explanation, which it sends in an X-Error-Message header and huggingface_hub tacks on the end. Newer releases word the first line differently. We read the code in 2.0.0, and a log in huggingface/kernels#640 shows the result:

huggingface_hub.errors.HfHubHTTPError: (Request ID: Root=1-6a2d24c0-614bb9854003adb23b4e8fc3;0d7e38c0-8542-47df-9bd3-96fdae3f917a)

429 Too Many Requests: you have reached your 'api' rate limit.
Retry after 122 seconds (0/3000 requests remaining in current 300s window).
Url: https://huggingface.co/api/models/kernels-community/deep-gemm/refs.

About 300 GitHub issues and pull requests quote the older line with a huggingface.co address, as of September 25, 2026. A lot of them are CI jobs, where many runners share one IP address.

Which of the three limits you hit

Hugging Face's rate-limit page splits requests into three buckets. "API" is the Hub API: search, repo info, listing files. "Resolvers" are file downloads, any URL with /resolve/ in it, which is what transformers, vLLM or LM Studio fetch weights through. "Pages" are the website itself. Each bucket counts over a fixed five-minute window.

The word in quotes in the newer message ('api' above) names the bucket. Raw responses carry it in a header too, like this one from lance-format/lance#5404, where r is requests left, t is seconds until the reset, q is the quota and w the window:

"ratelimit": "\"api\";r=0;t=138", "ratelimit-policy": "\"fixed window\";\"api\";q=3000;w=300"

The docs' table (dated September 2025) gives an anonymous IP address 500 API calls, 3,000 downloads and 100 pages per window. A free account gets 1,000, 5,000 and 200, and PRO gets 2,500, 12,000 and 400. Hugging Face says the anonymous and free numbers can change with platform load.

The fix that clears most of these

The docs are direct about it: not passing HF_TOKEN is "the number one reason users get rate limited." Without a token every request counts against your IP address at the anonymous rate, and on a shared runner or a cloud box that IP isn't only yours. Set the HF_TOKEN environment variable or run hf auth login, and make sure the token reaches whatever is doing the downloading (a Docker container won't see your shell's variables unless you pass them in).

If you're already logged in, the fixes left are slower requests, fewer API calls, or a bigger plan. The docs suggest swapping API calls for download (resolver) calls where you can, since that bucket's limit is much higher. A loop that calls model_info or lists refs for every file burns the small API bucket fast.

Does huggingface_hub retry on its own?

Partly. In 2.0.0 the retry helper tries up to five more times on a 429, and when the header says zero requests remain it sleeps for the reset time plus one second. With the 138-second reset above, the code would log Rate limited. Waiting 139.0s before retry [Retry 1/5]. The docs say this covers file downloads and paginated API listings (from version 1.2.0), so a single model_info call can still fail straight away. If the wait it quotes is a few minutes, sitting it out works. If you keep hitting the ceiling every window, your code is making too many calls.

One thing we noticed: organization plans are per member. The docs say a Team org's limit applies to each member separately, so one busy teammate doesn't use up yours.