Błędy kluczy API: poradnik

Klucz API nie działa? Napraw błędy 401, 402, 403 i 429

Dlaczego klucz API do AI przestaje działać: co znaczą błędy 401, 402, 403 i 429, jakiego kodu każdy dostawca używa przy pustym saldzie i jak to naprawić.

Zaktualizowano
  • Gdy klucz API do AI „nie działa”, numer błędu mówi, dlaczego: 401 oznacza, że błędny jest sam klucz, 402 — zwykle, że skończyło się saldo lub kredyty, 403 — że klucz nie ma uprawnień do danej operacji, a 429 — że wysłano za dużo żądań albo, u niektórych dostawców, że saldo jest puste.
  • Dostawcy nie są zgodni co do kodu pustego salda. DeepSeek, OpenRouter, Mistral, Together, Fireworks i przedpłacone rozliczenia Gemini używają 402; OpenAI, Kimi i Z.ai — 429; Qwen od Alibaba Cloud — 403. Czytaj treść komunikatu, nie tylko numer.
  • Błąd braku środków nie zniknie, nawet jeśli poczekasz, a limit żądań zwykle sam mija. Tabela niżej podaje oficjalną stronę błędów każdego dostawcy, sprawdzoną 18 listopada 2026 r.
Oriveo na iPhonie: ekran dostawców z listą podłączonych dostawców i wydatkami z tego miesiąca.

Co tak naprawdę znaczy „klucz API nie działa”?

Klucz API to tajny kod, który aplikacja dołącza do każdego żądania, żeby dostawca AI wiedział, że to ty, i z czyjego konta pobrać opłatę. Gdy coś pójdzie nie tak, dostawca odpowiada błędem: trzycyfrowym numerem, nazywanym kodem statusu HTTP, oraz krótkim komunikatem.

Numer mówi, jakiego rodzaju jest problem, a komunikat podaje szczegóły. Oriveo zamienia najczęstsze błędy na proste tytuły, takie jak „Nieprawidłowy klucz API” czy „Osiągnięto limit dostawcy”, omówione niżej na tej stronie.

Szybka ściąga: 401, 402, 403, 429 i 5xx

Zacznij tutaj. Znajdź swój numer, a potem przeczytaj odpowiednią sekcję niżej. To podsumowanie opiera się na stronach błędów OpenAI, Anthropic i innych dostawców według stanu na 18 listopada 2026 r.

Szybka ściąga: 401, 402, 403, 429 i 5xx
KodCo zwykle oznaczaCzy czekanie pomoże?Co zrobić
401Klucz jest błędny: brakuje znaku, jest dodatkowa spacja, klucz został usunięty albo pochodzi od innego dostawcy lub z innego regionuNieSkopiuj klucz ponownie albo utwórz nowy; sprawdź dostawcę i region
402Wymagana płatność: skończyło się przedpłacone saldo lub kredyty albo jest problem z rozliczeniamiNieDoładuj konto albo popraw metodę płatności na stronie rozliczeń dostawcy
403Klucz działa, ale nie ma uprawnień: nieobsługiwany kraj lub region, brak dostępu do tego modelu albo wymagana weryfikacjaNieSprawdź obsługiwane regiony, uprawnienia klucza i ewentualną weryfikację
404Błędna nazwa modelu albo adresNieWybierz inny model albo sprawdź adres
429Za dużo żądań w krótkim czasie albo, u niektórych dostawców, puste saldo lub limit wydatkówCzęsto tak, jeśli to limit żądańOdczekaj i spróbuj ponownie; jeśli komunikat wspomina o quota, balance, credit lub spend limit (limit, saldo, kredyty, limit wydatków), doładuj konto albo podnieś limit
500–504, 529Awaria lub przeciążenie po stronie dostawcyZwykle takSpróbuj później albo zmień model

Dlaczego pojawia się „insufficient balance” lub „quota”?

Większość dostawców wymaga przedpłaconych środków albo aktywnej metody płatności, zanim API zacznie działać, a każdy zgłasza puste saldo na swój sposób. W żadnym z tych przypadków nowy klucz nie pomoże; pomoże doładowanie.

Poniżej kod, który każdy z 15 wbudowanych dostawców Oriveo podaje w dokumentacji na wypadek wyczerpania salda lub kredytów. „Nie podano” oznacza, że dokumentacja dostawcy, sprawdzona 18 listopada 2026 r., nie podaje dla tej sytuacji kodu HTTP.

Dlaczego pojawia się „insufficient balance” lub „quota”?
DostawcaKod przy wyczerpanym saldzieTreść komunikatuOficjalna strona
OpenAI429credit_balance_exhausted (typ błędu może nadal brzmieć insufficient_quota)developers.openai.com/api/docs/guides/error-codes
Anthropic (Claude)Nie podano„Your credit balance is too low to access the Anthropic API”; problemy z płatnością zwracają 402 billing_errorplatform.claude.com/docs/en/api/errors (kody); platform.claude.com/docs/en/about-claude/api-credits-for-subscribers (komunikat)
Google Gemini402 (rozliczenia przedpłacone)payment_required; 403 może też oznaczać niezapłacone saldo w Cloud Billingaistudio.google.com/docs/api-errors
OpenRouter402Na koncie lub kluczu API brakuje kredytów (insufficient credits)openrouter.ai/docs/api-reference/errors
DeepSeek402Insufficient Balanceapi-docs.deepseek.com/quick_start/error_codes
xAI (Grok)Nie podanoŻądania są odrzucane, gdy skończą się przedpłacone kredytydocs.x.ai/console/billing
Mistral AI402Payment requireddocs.mistral.ai/resources/error-glossary
GroqBrak w dokumentacjiGroq nalicza opłaty po wykorzystaniu; jego strona błędów nie wymienia błędu saldaconsole.groq.com/docs/errors
Together AI402Payment Requireddocs.together.ai/docs/error-codes
Fireworks AI402Payment Requireddocs.fireworks.ai/guides/inference-error-codes
MiniMaxNie podano (kod biznesowy 1008)insufficient balanceplatform.minimax.io/docs/api-reference/errorcode
Z.ai (GLM)429 (kod 1113)Insufficient balance or no resource package. Please recharge.docs.z.ai/api-reference/api-code
Qwen (Alibaba Cloud)403Arrearage lub isv.OUT_OF_SERVICE (zaległości na koncie)alibabacloud.com/help/en/model-studio/error-code
Kimi (Moonshot AI)429exceeded_current_quota_errorplatform.kimi.ai/docs/api/errors
SiliconFlowBrak w dokumentacjiNie wymieniono błędu saldadocs.siliconflow.com/en/faqs/error-code

401: nieprawidłowy klucz API lub błąd uwierzytelniania

401 oznacza, że dostawca nie rozpoznaje klucza. Typowe komunikaty to „Incorrect API key provided” (OpenAI), „authentication_error” (Anthropic), „Authentication Fails” (DeepSeek) i „Invalid API key: this is not an OpenRouter API key” (OpenRouter).

  • Skopiuj klucz ponownie ze strony dostawcy i sprawdź, czy nie brakuje znaków i czy na początku lub końcu nie ma spacji.
  • Upewnij się, że klucz należy do wybranego dostawcy. Klucz OpenAI nie zadziała jako klucz OpenRouter i odwrotnie.
  • Kimi, MiniMax i Qwen prowadzą osobne platformy regionalne, a klucz z jednej nie działa na innej. W Oriveo wybierz pasujący region w selektorze „Oficjalny punkt końcowy” (na iPhonie: „Oficjalny adres URL żądania”).
  • Jeśli klucz został usunięty, unieważniony albo wygasł, utwórz nowy.

402: wymagana płatność lub niewystarczające saldo

402 dotyczy pieniędzy: przedpłacone saldo jest puste albo płatność się nie powiodła. Doładuj konto lub zaktualizuj dane płatności na stronie rozliczeń dostawcy, a potem wyślij ponownie. Czekanie nie pomaga.

W Oriveo wygląda to tak: „Osiągnięto limit dostawcy” — „Dostawca zgłasza, że limit lub środki dla tego klucza API zostały wyczerpane. Sprawdź rozliczenia u dostawcy lub przełącz model.”

403: brak dostępu lub odmowa uprawnień

403 oznacza, że dostawca rozpoznał klucz, ale nie zezwala na żądanie. Powód zależy od dostawcy:

  • OpenAI zwraca „Country, region, or territory not supported”, gdy API jest używane z kraju, którego nie obsługuje. Każdy dostawca publikuje listę obsługiwanych krajów.
  • Gemini zwraca 403, gdy projekt w bezpłatnym poziomie wymaga weryfikacji (FREE_TIER_VERIFICATION_REQUIRED), gdy powiązane konto Cloud Billing ma niezapłacone saldo albo gdy Google zablokował klucz zgłoszony jako ujawniony.
  • Anthropic zwraca permission_error, gdy klucz nie może korzystać z danego zasobu; sprawdź ustawienia organizacji i obszaru roboczego (workspace).
  • OpenRouter zwraca 403, gdy żądanie zostało zablokowane przez uprawnienia, moderację, zabezpieczenie (guardrail) lub limit budżetu.
  • SiliconFlow wymaga weryfikacji tożsamości przy niektórych modelach.
  • Qwen używa 403 przy zaległościach na koncie oraz w przypadku AllocationQuota.FreeTierOnly, gdy darmowy limit się wyczerpał, a ustawienie „Free Quota Only” jest włączone.

429: za dużo żądań, limit żądań lub przekroczony limit (quota)

Najczęściej 429 oznacza, że w krótkim czasie wysłano za dużo żądań lub tokenów. To limit żądań (rate limit), który mija, jeśli odczekasz kilkadziesiąt sekund. Jeśli odpowiedź zawiera czas Retry-After, odczekaj właśnie tyle.

Kilku dostawców używa 429 także przy pustym saldzie lub limicie wydatków — a wtedy czekanie nie pomoże: OpenAI (credit_balance_exhausted albo ustawiony przez ciebie limit wydatków), Kimi (exceeded_current_quota_error), Z.ai (kod 1113) oraz Anthropic, gdy organizacja osiągnie miesięczny limit wydatków (enforced_spend_limit_reached), który obowiązuje do następnego miesiąca, chyba że poprosisz o wyższy poziom (tier).

Darmowe poziomy są bardziej restrykcyjne. Bezpłatny poziom Gemini i darmowe modele OpenRouter mają limity na minutę i na dzień.

W Oriveo limit żądań pojawia się jako „Przekroczono limit żądań” w wersji webowej lub „Dostawca ograniczył liczbę żądań” na iPhonie i Androidzie. Jeśli komunikat wspomina o limicie (quota) albo kredytach, Oriveo pokazuje zamiast tego „Osiągnięto limit dostawcy”.

Co oznaczają komunikaty o błędach w Oriveo?

Tak brzmią komunikaty, które możesz zobaczyć w polskiej wersji Oriveo:

Co oznaczają komunikaty o błędach w Oriveo?
Co pokazuje OriveoCo to oznaczaCo zrobić
Zapisano, ale klucz wygląda na nieprawidłowy. Możesz go zweryfikować później w ustawieniach dostawcy.Oriveo zapisało dostawcę, ale ten odrzucił klucz podczas sprawdzaniaSkopiuj klucz ponownie i zaktualizuj go w ustawieniach tego dostawcy
Nieprawidłowy klucz APIDostawca zwrócił 401 lub 403Sprawdź lub wymień klucz; przy 403 sprawdź region i uprawnienia
Osiągnięto limit dostawcyDostawca zgłasza, że środki lub limit dla tego klucza się wyczerpały (402 albo 429 ze wzmianką o limicie)Doładuj konto u dostawcy albo przełącz się na inny model
Przekroczono limit żądań / Dostawca ograniczył liczbę żądańNa razie za dużo żądań (429)Odczekaj chwilę i spróbuj ponownie
Osiągnięto bezpłatny limitDzisiejszy limit Oriveo Free się wyczerpał; nie ma to nic wspólnego z twoim kluczemDodaj własny klucz API albo poczekaj na odnowienie o 00:00 UTC
Ekran „Dostawcy” w Oriveo z listą podłączonych dostawców, takich jak OpenAI, Z.ai, Groq, Gemini i Anthropic, każdy z wydatkami
Otwórz dostawcę z tej listy, aby sprawdzić lub wymienić jego klucz.

Korzystasz z własnego punktu końcowego, usługi pośredniczącej lub bramki?

Jeśli łączysz się przez własny punkt końcowy, błąd może pochodzić od tej usługi albo od dostawcy, który za nią stoi. Gdy Oriveo pisze „To połączenie nie mogło połączyć się z dostawcą nadrzędnym”, konto tej usługi u dostawcy może być nieważne, bez środków lub objęte limitem żądań. To nie wina twojej konfiguracji; przełącz się na inne połączenie albo skontaktuj się z tym, kto prowadzi tę usługę.

Sprawdź to, zanim utworzysz nowy klucz

Nowy klucz naprawia błąd 401 i niewiele więcej. Najpierw przejdź przez tę listę:

  • Wybrano właściwego dostawcę, a w przypadku Kimi, MiniMax, Qwen, SiliconFlow i Z.ai także właściwy region.
  • Skopiowano cały klucz, bez spacji.
  • Na koncie są środki albo aktywna metoda płatności.
  • Twój kraj lub region jest na liście obsługiwanych przez dostawcę.
  • Wybrany model jest dostępny dla twojego konta lub poziomu (tier).

Najczęstsze pytania

Dlaczego mój klucz API nie działa?
Spójrz na numer błędu. 401 oznacza, że klucz jest błędny, 402 — że skończyło się saldo lub kredyty, 403 — że żądanie jest niedozwolone (często przez region lub uprawnienia), a 429 — że wysłano za dużo żądań albo, u niektórych dostawców, że saldo jest puste.
Co oznacza błąd 401 przy kluczu API?
Dostawca nie rozpoznaje klucza. Skopiuj go ponownie bez spacji, sprawdź, czy należy do wybranego dostawcy i regionu, albo utwórz nowy klucz.
Co to jest błąd 402 Payment Required?
Skończyło się przedpłacone saldo lub kredyty albo wystąpił problem z płatnością. Używają go DeepSeek, OpenRouter, Mistral, Together, Fireworks i przedpłacone rozliczenia Gemini. Doładuj konto na stronie rozliczeń dostawcy; czekanie nic nie da.
Błąd 429 to limit żądań czy brak środków?
Może oznaczać jedno albo drugie. Zwykle to limit żądań, który mija po krótkiej chwili. Jednak OpenAI, Kimi i Z.ai zwracają 429 także przy pustym saldzie, więc jeśli w komunikacie pojawia się quota, balance lub credit, doładuj konto zamiast czekać.
Dlaczego mój klucz API OpenAI zwraca insufficient_quota?
Na twoim koncie API OpenAI nie ma już przedpłaconych środków. OpenAI zwraca 429 z kodem credit_balance_exhausted, a typ błędu może nadal brzmieć insufficient_quota. Dodaj środki w ustawieniach rozliczeń OpenAI; nowy klucz nie pomoże.
Dlaczego nowy klucz API nie działa, choć skopiowano go poprawnie?
Zwykle dlatego, że na koncie nie ma jeszcze środków lub nie skonfigurowano płatności, klucz należy do innego regionu albo API nie jest dostępne w twoim kraju. Sprawdź to, zanim utworzysz kolejny klucz.

Powiązane lektury

Zrozumiałe komunikaty o błędach dla każdego klucza

Otwórz wersję webową albo pobierz Oriveo na iPhone’a lub Androida, dodaj klucze od 15 dostawców i zobacz jasny powód, gdy żądanie się nie powiedzie.

Nie masz jeszcze klucza API? Zacznij od Oriveo Free.