기본 콘텐츠로 건너뛰기

Hugging Face Inference Errors Fixed: 401, Credits, Providers

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

  1. 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.
  2. Export it as HF_TOKEN and pass it as Authorization: Bearer $HF_TOKEN, or as api_key when you use the OpenAI client with base_url="https://router.huggingface.co/v1".
  3. If you use the Python InferenceClient without passing a key, it falls back to a token stored by hf auth login. On a server, CI runner or container that login usually does not exist, so pass the key explicitly there.
  4. Check for a stray space, a missing Bearer prefix, 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

  1. Open huggingface.co/settings/billing and check your balance and rate-limit status.
  2. 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.
  3. 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 for openai/gpt-oss-120b it returned "inference":"warm". For the docs' example manycore-research/SpatialLM-Llama-1B the field was missing entirely, which means no provider serves it.
  • For chat models, https://router.huggingface.co/v1/models lists 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 NAME does the same check with the hf CLI.

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

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

Uploaded Image Uploaded Image Uploaded Image Uploaded Image

댓글

이 블로그의 인기 게시물

브루(Vrew) 요금제 정리: 무료 200크레딧으로 어디까지 쓸 수 있나

요약: 영상 자막 편집기 브루(Vrew)는 2026년 4월 22일부터 기능별 사용량 대신 '통합 크레딧' 하나로 요금을 매겨요. 무료 플랜은 매달 200크레딧이 들어오는데, 음성 분석(자동 자막)만 쓰면 최대 200분 분량이라 짧은 영상 몇 편은 충분하지만, 영상 초반의 Vrew 마크를 지우려면 유료 플랜이 필요해요. 이 글은 브루 공식 가격 페이지와 고객센터 공지를 2026년 10월 23일에 다시 확인해, 크레딧 계산법과 플랜 고르는 기준을 정리했어요. 목차 브루 요금 구조: 통합 크레딧이란 1크레딧으로 할 수 있는 일 무료 플랜으로 되는 것과 안 되는 것 유료 플랜 4종 비교표 월 구독·연 구독·기간 이용권, 무엇이 이득일까 상황별 추천: 학생·직장인·유튜버 크레딧이 모자랄 때: 사용 기록 지우개 업그레이드·환불 전에 알아둘 규칙 운영자 메모, 자주 묻는 질문 1. 브루 요금 구조: 통합 크레딧이란 예전 브루는 플랜마다 음성 분석 몇 분, AI 목소리 몇 자, 번역 몇 자처럼 기능별 한도를 따로 줬어요. 그런데 보이저엑스(브루 운영사)가 실제 이용 데이터를 보니 한두 가지 기능만 집중해서 쓰는 사람이 훨씬 많았다고 해요. 그래서 2026년 4월 22일 업데이트부터는 플랜마다 정해진 크레딧을 받고, 어떤 기능에 쓸지는 내가 정하는 방식으로 바뀌었어요. 플랜별 매달 지급량은 Free 200 · Light 2,000 · Standard 10,000 · Business 12,000크레딧 이에요. 공식 공지에 따르면 무료 사용자는 매달 1일에, 유료 사용자는 매월 결제일에 충전되고, 남은 크레딧은 다음 달로 넘어가지 않아요. 바뀐 뒤 무엇이 좋아졌나 공지에 나온 예시가 이해하기 쉬워요. Standard 플랜에서 AI 목소리만 쓰면 예전에는 최대 50만 자였지만, 지금은 1만 크레딧을 모두 AI 목소리에 몰아 쓸 수 있어 최대 100만 자가 돼요. 반대로 여러 기능을 골고루 쓰는 사람은 크레딧이 기능끼리 ...

에이닷 전화 vs 익시오: 통화 녹음·AI 요약, 내 통신사·폰에 맞는 앱 고르기

요약: 통화 녹음과 AI 요약을 쓰고 싶다면 먼저 내 통신사와 휴대폰 종류부터 확인해야 해요. LG유플러스 고객은 무료 앱 익시오, SKT 고객은 에이닷 전화가 가장 기능이 많고, 다른 통신사의 아이폰 사용자는 iOS에 들어 있는 기본 통화 녹음·전사 기능이 현실적인 선택이에요. 이 글은 2026-10-30에 SKT·LG유플러스·Apple 공식 페이지와 도움말을 직접 확인해 세 가지를 비교했어요. 왜 '앱 기능'보다 '내 조건'을 먼저 봐야 할까요 통화 요약 앱 비교 글을 보면 기능 목록부터 나열하는 경우가 많아요. 그런데 실제로 써 보려는 사람에게 가장 먼저 걸리는 건 기능이 아니라 이용 조건 이에요. 익시오는 LG유플러스 고객 전용이고, 에이닷 전화는 누구나 설치할 수 있지만 통역콜·baro 같은 기능은 SKT 고객에게만 열려 있어요. 아이폰은 운영체제 구조상 앱이 통화를 마음대로 녹음하기 어려워서, 통신사 앱이 안 되면 iOS 기본 기능에 기대야 해요. 그래서 이 글은 "어떤 앱이 제일 좋은가"보다 "내 통신사·내 폰에서 무엇을 쓸 수 있나" 순서로 정리했어요. 기능 차이는 그다음이에요. 한눈에 비교: 에이닷 전화 vs 익시오 vs 아이폰 기본 통화 녹음 구분 에이닷 전화 (SKT) 익시오 ixi-O (LG유플러스) 아이폰 기본 통화 녹음 (Apple) 누가 쓸 수 있나 통신사 구분 없이 앱 설치 가능. 단, 통역콜·baro·그룹통화 발신 등은 SKT 고객 전용 U+ 모바일 고객. 타 통신사, 만 14세 미만, 선불요금제 고객은 제한 (공식 사이트 FAQ상 알뜰폰 중 KB리브엠은 예외) 지원 국가·언어의 iPhone 사용자. 1명과 통화할 때만 녹음 가능 지원 OS·기기 Android 10 이상, iOS 16 이상 iOS 17 이상 iPhone 12 이상 / Android...

타입캐스트 vs 클로바더빙: 수익 나는 채널에 쓸 때 무료·유료 조건 비교

요약 타입캐스트와 클로바더빙은 둘 다 글만 입력하면 한국어 AI 목소리를 만들어 주는 서비스지만, 무료로 쓸 수 있는 범위가 꽤 다릅니다. 클로바더빙 무료는 매달 15,000자까지 쓸 수 있는 대신 수익이 생기는 채널에는 쓸 수 없고, 타입캐스트 무료는 처음에 주는 약 5분 분량의 다운로드로 끝나는 체험판에 가깝습니다. 광고 수익이 붙은 유튜브나 쇼핑몰 영상에 넣을 목소리라면 처음부터 유료 플랜 조건을 보고 고르는 편이 안전합니다. 왜 이 두 서비스를 같이 비교하나 쇼츠 내레이션, 수업 자료 더빙, 상품 소개 영상처럼 "내 목소리 대신 AI 목소리"가 필요할 때 한국 사용자들이 가장 많이 찾는 곳이 네오사피엔스의 타입캐스트 와 네이버의 클로바더빙 입니다. 기능 소개만 보면 비슷해 보이지만, 실제로 문제가 되는 건 음질보다 "이 목소리를 내 채널에 써도 되나" 입니다. 그래서 이 글은 기능 나열보다 무료 사용 범위, 출처 표기 의무, 유료 플랜 가격과 다운로드 한도를 중심으로 정리했습니다. 모든 수치는 2026년 10월 25일에 두 서비스의 공식 요금 페이지와 고객센터 도움말에서 직접 다시 확인한 내용입니다. 한눈에 보는 비교표 항목 타입캐스트 무료 타입캐스트 베이직 클로바더빙 Free 클로바더빙 Standard 월 요금 0원 9,900원 (연간 결제 시 10% 할인) 0원 19,900원 (네이버 클라우드 플랫폼에서 결제) 무료·포함 사용량 음성 생성·재생 무제한, 다운로드는 최초 3,000크레딧(약 5분) 1회 지급 월 30,000크레딧(약 60분) 월 15,000자, 다운로드 월 20회, 프로젝트 누적 5개 (매월 1일 갱신) 월 30,000자, 다운로드 월 40회, 프로젝트 누적 20개 쓸 수 있...