Hugging Face errors 429, 403 and 418 explained
Last updated: 2026-09-01
A 429 from huggingface.co means you crossed a rate limit, not that you are banned. The limits run in fixed five-minute windows, your own response headers say how many seconds are left on yours, and for most people the fix is a token, a pause, or a download that makes fewer requests. The codes around it get mistaken for it constantly: 401 and 403 are access problems, 404 is a naming problem, and 418 is the one code Hugging Face does not document anywhere.
Three lines sort almost everyone who lands here.
Which error do you have?
429: a rate limit. You asked too often inside one of three counted buckets, and the window resets on its own schedule. The response headers tell you which bucket and how long. Decoder row.401or403: an access problem. The request arrived and was refused: no token, a mistyped name, a gated repo without a grant, or a token that lost its permission. Decoder row.418: undocumented. Hugging Face's rate limits page and its own SDK never mention the code, and the SDK does not retry it. Community reports describe an IP-level block on signup and login, and that is all anyone outside Hugging Face can honestly say. Decoder row.
The error decoder
People arrive with a string, not a diagnosis: a traceback, a dead curl line, a red status in a log. This table is the diagnosis step. Every meaning carries its source, and where no document exists, the row says so instead of inventing one.
| Code | What the response tells you | Check this first | Source |
|---|---|---|---|
| 429 on any request | You crossed a rate limit. Limits are counted in three buckets: Hub API calls, resolvers (every URL containing /resolve/), and Pages. Windows are fixed at five minutes. | Your ratelimit headers. The policy names the bucket; the other says seconds to reset. | Rate limits doc |
| 401 on a model you know exists | The repo is restricted or private and you sent no token. A repo that does not exist returns the same code, so a typo and a permission refusal look identical from outside. | The repo id, character by character. Then a token. | huggingface_hub error utilities |
| 403 on a gated repo | Authenticated but not authorized. The grant is missing, the fine-grained token is not scoped for that repo, or an organization denied or revoked the token. Owners can revoke access at any time. The library raises GatedRepoError, its message starting "Cannot access gated repo". | The repo page in a browser, logged in: is there an access form, and what does it say? | Gated models doc, Access tokens doc |
| 403 from wget or curl on a URL the browser opens | Has happened as a server-side bug, later fixed by Hugging Face staff. Some 403s are not your fault. | One retry, then the same URL in a browser. | Community report: a forum thread with a staff reply. No doc covers it. |
| 404 on a file or revision | The filename, branch, or revision is wrong for that repo. | The file list at the revision you expect, not at main. | huggingface_hub error utilities |
| 418 on signup or login | Not documented. Absent from the rate limits doc and from the SDK's retry list. Community reports describe an IP-level block on signup and login, with staff offering manual review. | The error text itself: it names a contact address. | Negative finding against the rate limits doc; community reports only |
In Python the same facts arrive as exceptions rather than codes. RepositoryNotFoundError covers the 401-shaped cases, GatedRepoError is the gated 403, and RevisionNotFoundError and EntryNotFoundError cover the 404 family. The string people actually paste into a search box is usually the requests library's rendering of the limit: 429 Client Error: Too Many Requests for url. That is a rate limit like any other, and the rest of this page applies.
One body text is worth recognizing on sight. Fetch a gated model with no token and the 401 spells the situation out. Captured 2026-09-01 from an unauthenticated request against meta-llama/Llama-3.1-8B-Instruct:
Access to model meta-llama/Llama-3.1-8B-Instruct is restricted. You must
have access to it and be authenticated to access it. Please log in.If your error says that, the model exists, it is gated, and your next step is the access form, not more debugging. If it does not say that and the repo id is right, you are looking at a private repo or a nonexistent one, and from outside those two look the same by design.
One more signal, with a limit on how far to trust it. Refusals can arrive with an x-error-code response header, GatedRepo on a gated refusal for example. Hugging Face responses expose the header name, but no documentation page defines its values. Treat it as something you observed, not a contract.
If the code is 418, stop guessing. Hugging Face documents nothing about it: the rate limits page never mentions the code, and the SDK's retry list skips it. Everything known beyond that comes from community reports, which describe an IP-level block on the signup and login pages and a contact address inside the error text for asking a human. Wait, use that address, and be skeptical of anyone selling a one-click fix.
Read your own limit numbers
This is the check almost nobody runs, and it settles in one command whether the problem is your token, your address, or your plan. Every rate-limited response from the Hub carries two headers that name your bucket and your countdown. Ask for any file's headers and read them:
curl -I https://huggingface.co/Qwen/Qwen2.5-7B-Instruct/resolve/main/config.json
curl -I https://huggingface.co/api/models/Qwen/Qwen2.5-7B-InstructThe first URL is a resolver, the bucket your downloads and per-file metadata calls spend. The second is the Hub API bucket. curl does not follow redirects unless you add -L, and here you should not: the interesting headers ride the first response, before the file URL resolves toward the storage and CDN hosts behind huggingface.co. That redirect is also why allowlisting the API host alone is not enough if you filter outbound traffic; the models-downloading doc carries the allowlist table.
| Header | What it tells you |
|---|---|
ratelimit-policy | The bucket you are in (its scope), the quota q, and the window w in seconds. |
ratelimit | What you have left, r, and the seconds until the window resets, t. |
A worked example, captured 2026-09-01 from one unauthenticated IP. The file URL reported a policy of resolvers with q=3000 in a w=300 second window. The API URL reported api with q=500 in the same 300 seconds. After one request, the resolver header read r=2999 with t=51 seconds to reset. Those numbers belong to that address on that day. Yours move with your plan tier, and anonymous quotas are counted per IP, so anyone sharing your address shares your bucket.
The sixty-second version: one curl -I against the URL that failed, two headers read, and you know which bucket you spent, how much is left, and when it resets. That beats any forum thread, because it is your number, not someone else's.
The three buckets explain which of your commands is the expensive one. Hub API calls sit in one bucket. Resolvers, which serve every URL containing /resolve/, sit in another, and file downloads and the per-file metadata calls of a snapshot download both hit it. Pages is the third. A repository of many small files does not exhaust anything by being big; it exhausts the resolver bucket because a snapshot makes one metadata call per file, a cost the huggingface_hub issue tracker documents in plain terms. The command line client and the Python library spend the same buckets; there is no documented client that opts out.
Your download code already reads these numbers. huggingface_hub 1.2.0 and later takes the reset time from the headers and waits exactly that long before retrying, so a current library turns most 429s into a pause you never see. The SDK's default retry list covers 408, 429, 500, 502, 503, and 504. Notice what is missing from that list: 418, the code nobody documents, is also the code the SDK will not retry for you.
Anonymous traffic is counted per IP address, which is the part that breaks shared environments. Cloud notebooks, CI runners, and office networks put many machines behind one address, so a script that worked at home can arrive at a bucket other people already spent. The script did not change; the address did.
Fixes by situation
Situations, not codes, because two people with the same 429 need opposite fixes. The first two columns are documented behavior or the pattern people converge on in practice; the last column is where we tell you not to spend your afternoon.
| Situation | First fix | Then | Do not bother | Read more |
|---|---|---|---|---|
| Anonymous and hitting 429 | Set HF_TOKEN. It is the first fix in the rate limits doc: logged-in requests count against your account's higher numbers instead of your IP's. | Re-run the header check with the token and read your new policy. | A retry loop with no token and no pause. The window is five minutes, and hammering does not shorten it. | The header check |
| Logged in and still hitting 429 | Read the headers and find which bucket is empty. API and resolver limits are separate. | Download once into a cache your jobs share, then load from disk (local_files_only=True), so nothing asks the Hub again. | More parallel connections. Same bucket, spent faster. | Rate limits doc |
| Many workers on one IP | Put the token on every worker, not only the head node. | One download into shared storage, every worker pointed at the local copy. If jobs share a cache directory, lock it so two do not fetch the same file at once. | More machines behind the same address. Anonymous limits count the address, not the machine. | huggingface_hub issue 4722 |
| A repo with thousands of small files | One snapshot download, left alone to finish. | Upgrade the library: old datasets releases made a strongly rate-limited call shape (expand=True in the traceback) that newer releases dropped. | A hand-written per-file walker. Each file costs a metadata call, so thousands of files are thousands of calls. | datasets issue 7344 |
| 403 on a gated repo | Request access in the browser, logged in. The form asks you to agree and share contact info, and approval is automatic or manual per repo. | Send a read token with the script. Read is the role for downloads, gated repos included. | Your SSH key. It works for git, not for the API a download script calls. | Gated models doc, Access tokens doc |
| 401 with no token | Check the repo id character by character. A repo that does not exist returns the same 401 a restricted one does. | Send a token. If the model is restricted the body says so plainly; see the captured text above. | Concluding the model was deleted. Of the three explanations, it is the least likely. | huggingface_hub error utilities |
| 418 on signup or login | Wait it out, and stop automated retries against the login flow. | Use the contact address inside the error text to ask for a manual review. Staff have offered exactly that. | Changing networks. People report it as a workaround, and it is not a fix we recommend. | The 418 decoder row |
The structural way out
Sometimes the diagnosis is finished and the answer is still annoying: the workload needs a big openly licensed model, regularly, from one host that meters it. For openly licensed weights there is a distribution route with no rate limits and no auth wall: torrents. The trade is real. Nobody meters the download, so proving the bytes are right becomes your job, and the proof is a signed manifest. Every file carries a digest, sha256 for LFS files and sha1+size for git blobs, each labeled with the method actually used, and the whole list is covered by one minisign signature. Three commands check it end to end on the verify page, and the long walkthrough is the verification guide.
Two models from this archive show the shape. Qwen_Qwen2.5-7B-Instruct is apache-2.0, about 15 GB across 13 files. NousResearch_Hermes-3-Llama-3.1-8B carries the Llama license, about 16 GB across 11. Both were verified against upstream Hugging Face at fetch time, with the exact revision pinned in the manifest. How torrents carry models like these is its own guide, what the link hands your client is another, and the wider set of ways to get models without the Hub is a third.
What this does not solve: gated models stay gated, by their license terms, on every route, including this one. And the limits on Hugging Face exist for abuse reasons; they are documented, they are survivable, and nothing on this page is a complaint about them. The torrent route is the exit for one job: I need these open weights now, without asking permission or waiting out a window.
Which problem do you actually have?
Three problems share these search results, and they have different fixes.
- The Hub refused the request, with a code: 429, 401, 403, a stray 404, or 418. That is this page, and the matrix above is the exit.
- The download runs but crawls. Nothing was refused; the bytes are just slow. If your download is slow but not refused is that page.
- The error comes from the ollama command, not from a request you made. That client and its registry path get their own walkthrough: ollama pull slow.
Client setup and file formats are one click away on the help page, and the catalog carries everything this archive publishes at /models/.
Sources
Read in full while writing this page:
- Hugging Face: Rate limits, the three buckets, the tier table, the header format, and the token fix
- Hugging Face: Gated models
- Hugging Face: Access tokens
- Hugging Face: huggingface_hub error utilities
- Hugging Face: Downloading models
- huggingface_hub issue 4722, one metadata call per file in a snapshot download
- datasets issue 7344, the rate-limited call shape in old releases
Community-reported details on this page (the transient wget 403, the 418 reports, lockouts longer than the five-minute window) come from Hugging Face forum threads, several with staff replies. This site's citation policy keeps forum links out of articles, so those rows name their evidence where they stand.
Frequently asked questions
What does error 429 mean on Hugging Face?
It means you crossed a rate limit, not that you are banned. Limits are counted in three buckets (Hub API calls, resolvers which serve every /resolve/ URL, and Pages) over fixed five-minute windows, and the response headers tell you the bucket, the quota, and the seconds until reset. Anonymous traffic is counted per IP address.
How long does a Hugging Face rate limit last?
The window itself is five minutes, so a single burst clears on its own, and the SDK (1.2.0 and later) waits the exact stated seconds and retries for you. Community reports describe longer lockouts after heavy bulk operations, up to more than a day in one upload case, so if the block persists, stop hammering and let it reset.
Why do I get a 401 for a model I know exists?
Because restricted and private repos return 401 when you have no token, and a repo that does not exist can return the same code, so a typo in the name looks identical to a permission problem. Check the name first, then send a token; the error body spells out the restricted case in plain text.
Why do I get 403 on a gated model even after I was granted access?
Because the grant attaches to your account and the script is not sending your account: no token in that environment (notebooks and CI are the usual case), an SSH key where a token is needed, a fine-grained token scoped without that repo, or an organization that denied or revoked the token. Access itself can be revoked at any time by the repo owners.
Is Hugging Face error 418 a rate limit?
Hugging Face does not document 418 as a rate limit anywhere, and it is not in the SDK's retried status codes. Community reports describe it as an IP-level block on signup and login pages, sometimes with a generic contact message. What works for people: wait, avoid automated retries on the login flow, and use the contact address in the error text to ask for a manual review. We do not recommend VPN services as a fix.
Does a token remove the rate limit?
No. It moves you from the anonymous per-IP bucket to your account's bucket with higher documented numbers, and resolver traffic still counts. If your workload needs many files, the durable fixes are downloading once to a shared cache and loading locally, or taking the open-weights route with verification.