Summary: Most Hugging Face Inference Providers failures come from four places: the token, the credit balance, the model you picked, and the way the request is routed. This guide walks through each one in the order worth checking, with the exact endpoints and settings from Hugging Face's own documentation. Everything below was checked against the official docs and pricing page on 2026-11-03, and the 401 responses quoted here are ones I actually got back from the router while writing.
First, a 30-second map of how a request travels
Inference Providers is Hugging Face's single API in front of many inference companies, including Cerebras, Groq, Together, Fireworks, Novita, fal, Replicate and Hugging Face's own HF Inference. You send one request with one Hugging Face token to https://router.huggingface.co/v1 (the OpenAI-compatible route) or through the huggingface_hub / @huggingface/inference clients. Hugging Face then forwards it to a provider that serves that model.
That middle step is why errors can be confusing. A request can fail because Hugging Face rejected you (token, credits), because no provider serves your model for that task, or because the provider you forced is a bad match. Keep those three layers in mind and most problems sort themselves out quickly.
Error 1: 401 Unauthorized
This is the most common first error, and the response looks different depending on what went wrong. While writing this I sent the documented chat request to the router two ways:
- No Authorization header at all: the router answered HTTP 401 with a full HTML page that says "Unauthorized access. Please check your credentials or authorization". If your code tries to parse that as JSON, you will see a JSON decode error instead of a clean 401, which hides the real cause.
- A made-up token: HTTP 401 with a short JSON body,
{"error":"Invalid username or password."}. The wording mentions a password even though you sent a token, so do not let it send you off resetting your account password.
How to fix it
- Create a token at huggingface.co/settings/tokens. The docs recommend a fine-grained token with the permission Make calls to Inference Providers. A plain read token also works for inference according to the token docs, but a fine-grained one limits the damage if it leaks.
- Export it as
HF_TOKENand pass it asAuthorization: Bearer $HF_TOKEN, or asapi_keywhen you use the OpenAI client withbase_url="https://router.huggingface.co/v1". - If you use the Python
InferenceClientwithout passing a key, it falls back to a token stored byhf auth login. On a server, CI runner or container that login usually does not exist, so pass the key explicitly there. - Check for a stray space, a missing
Bearerprefix, or a token copied from the wrong account.
The organization version: 403
If you bill or access resources through an organization, a token can be valid for you but blocked for the org. The token docs list three cases that return 403: the token was denied by an org admin, it was revoked by an org admin, or the org requires fine-grained tokens and you sent a classic read or write token. Your token list shows a red exclamation icon on denied or revoked tokens, which is the fastest place to look.
Error 2: Requests fail because you have no credits
This is the change that catches the most people. Hugging Face's current pricing documentation lists no included monthly credits for free users. Free accounts can still use Inference Providers, but only after purchasing credits. PRO accounts get $2.00 of compute credits per month, and Team or Enterprise organizations get $2.00 per seat, shared across members.
Some older pages, including part of the huggingface_hub inference guide, still talk about monthly credits depending on whether you are Free, PRO or Enterprise. The pricing page and the Inference Providers pricing docs are the ones to trust.
How to fix it
- Open huggingface.co/settings/billing and check your balance and rate-limit status.
- Open the Inference Providers usage view in settings to see the past month's usage broken down by model and provider. If one model is eating the budget, that is where you will spot it.
- Either buy credits, upgrade to PRO, or switch that provider to your own provider key (see the routing section below), which moves billing off your Hugging Face balance entirely.
Note that PRO credits are general compute credits. They can also be spent on Inference Endpoints, Spaces hardware, ZeroGPU beyond quota and Jobs, so a busy Space can drain the same $2 your API calls rely on.
Error 3: The model does not work through the router
Not every model on the Hub is served by an inference provider. A model page can look perfectly normal and still have no provider behind it.
Check whether anyone serves the model
- Call
https://huggingface.co/api/models/OWNER/MODEL?expand[]=inference. When I tried it foropenai/gpt-oss-120bit returned"inference":"warm". For the docs' examplemanycore-research/SpatialLM-Llama-1Bthe field was missing entirely, which means no provider serves it. - For chat models,
https://router.huggingface.co/v1/modelslists what the OpenAI-compatible route can serve, with each provider's status, context length and per-million-token prices. No token is needed for this list. When I fetched it on 2026-11-03 it listed 133 chat models, and gpt-oss-120b alone had several live providers with different prices and speeds. - From a terminal,
hf models ls --warm --search NAMEdoes the same check with thehfCLI.
Check that the provider supports the task
Providers do not all support the same tasks. In the huggingface_hub support table, fal and Replicate support image, video and speech tasks but not chat completion, while HF Inference covers a wide set of classic tasks such as classification, fill-mask and embeddings. If you force provider="fal-ai" on a chat model, or provider="replicate" on an embedding call, the request has nowhere valid to go. Leave the provider on auto while you test, then pin one once it works.
HF Inference is not the old free serverless API
The hf-inference provider used to be called the Inference API (serverless). The docs say that since July 2025 it focuses mostly on CPU inference, such as embeddings, text ranking, text classification and small historical models like BERT and GPT-2. Older tutorials that point a large LLM at the legacy API are a common source of "model not supported" surprises. It is also billed now: compute time multiplied by the hardware price, once your included credits run out.
Error 4: Wrong provider, wrong price, or slow responses
By default the router picks the fastest provider for a model. You can change that with a suffix on the model id:
openai/gpt-oss-120b:fastest: highest throughput (the default).openai/gpt-oss-120b:cheapest: lowest price per output token.openai/gpt-oss-120b:preferred: follow your own order in Inference Provider settings.openai/gpt-oss-120b:groq: force one named provider.
If your bill looks higher than expected, the fastest provider is often not the cheapest one. The /v1/models list shows the spread clearly, so check it before you settle on the default. If latency suddenly jumps, a failover may have moved you to a slower provider; pinning a provider makes performance predictable at the cost of losing automatic fallback.
The Python client also waits indefinitely by default. Set InferenceClient(timeout=30) and catch InferenceTimeoutError so a stuck call does not hang your app.
Error 5: 429 Too Many Requests
Hugging Face documents 429 for the Hub's own rate limits, which are counted in 5-minute fixed windows and returned with RateLimit and RateLimit-Policy headers. The number one cause, according to the docs, is simply not sending a token: anonymous calls get the lowest limits per IP address. Pass HF_TOKEN everywhere, including to libraries that download models for you. huggingface_hub 1.2.0 and later reads the reset time from the header and waits exactly that long before retrying Hub calls.
Provider-side throttling is a separate layer. If you set a custom provider key, the limits of your account with that provider apply, so check that provider's dashboard as well.
Routed billing vs your own provider key
In your Inference Providers settings you can store your own API key for any integrated provider. Hugging Face then still routes the call, keeps your code unchanged (you keep passing the Hugging Face token) and swaps the authentication on the way through. The provider bills you directly and your Hugging Face credits are not used. The settings list also lets you reorder providers, which is what :preferred and the model-page widget follow.
A practical gotcha: in the official screenshots, providers show a "Billing disabled" badge in the settings list and the widget menu. The docs do not spell out every state behind that badge, so if a provider you rely on carries it, open its entry in settings and confirm how it is billed before you pin requests to it.
Plans compared: what changes for inference
| Plan | Price (pricing page) | Included inference credits | Hub API limit per 5 min | Extra usage |
|---|---|---|---|---|
| Free | $0 | None | 1,000 requests (subject to change) | Pay-as-you-go after buying credits |
| PRO | $9 per month | $2.00 per month, usable on all HF compute | 2,500 requests | Pay-as-you-go |
| Team | $20 per user per month | $2.00 per seat, shared by the org | 3,000 requests per member | Pay-as-you-go, org spending limit, bill via X-HF-Bill-To |
Rate limits are the Hub tiers from the rate-limit docs (dated September 2025 there); provider-side limits are separate. Hugging Face says it adds no markup to provider rates.
Editor's note
Who it's for: developers who want to try many open models (gpt-oss, GLM, DeepSeek, Llama, FLUX) through one OpenAI-style API and one bill, and teams who want usage centralised per member.
Not for: anyone expecting a free API. With no included credits on free accounts, a single-model app on one provider may be simpler on that provider directly or on a local runner.
Gotchas I verified: a missing header returns an HTML 401 page, not JSON; a bad token returns "Invalid username or password."; a model with no inference field in the Hub API is not served by any provider; the default policy is fastest, not cheapest.
Quick fixes: 401 → check Bearer and token permission; 403 on an org → fine-grained token or ask the admin; failing on cost → check billing and credits; model errors → check ?expand[]=inference and task support; 429 → always send a token and back off.
FAQ
Is Hugging Face Inference Providers free?
Not on a free account any more. The current pricing docs show no monthly inference credits for free users, so you need to buy credits or use PRO ($2.00 of monthly compute credits). With your own provider key, the provider bills you instead.
Why does my code show a JSON error instead of 401?
When the Authorization header is missing, the router returned an HTML error page in my test. Log the status code and raw body before parsing, and the real cause becomes obvious.
How do I make it use the cheapest provider?
Append :cheapest to the model id, for example openai/gpt-oss-120b:cheapest, or set your own order in settings and use :preferred.
Related guides on this blog
- OpenRouter Free Models: Limits, Fees and When to Pay (the other big multi-provider router)
- Groq API Free Tier: Rate Limits, Costs and When to Upgrade (if you would rather call one fast provider directly)
- Ollama Not Working? Fixes for Common Errors and GPU Issues (running open models locally instead)
Check the token, then the credits, then whether anyone serves the model, and most Inference Providers errors are gone in minutes.
Images: own screenshot of the Hugging Face pricing page plus official screenshots from the Hugging Face Inference Providers documentation (huggingface.co); see them at the end of this post.
Last verified: 2026-11-03
Sources:
Hugging Face Docs: Inference Providers
Hugging Face Docs: Pricing and Billing
Hugging Face Docs: Hub API
Hugging Face Docs: Hub Integration
Hugging Face Docs: User Access Tokens
Hugging Face Docs: Hub Rate Limits
huggingface_hub: Run Inference on Servers
Hugging Face Pricing
댓글
댓글 쓰기