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ć.
- 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.

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.
| Kod | Co zwykle oznacza | Czy czekanie pomoże? | Co zrobić |
|---|---|---|---|
| 401 | Klucz jest błędny: brakuje znaku, jest dodatkowa spacja, klucz został usunięty albo pochodzi od innego dostawcy lub z innego regionu | Nie | Skopiuj klucz ponownie albo utwórz nowy; sprawdź dostawcę i region |
| 402 | Wymagana płatność: skończyło się przedpłacone saldo lub kredyty albo jest problem z rozliczeniami | Nie | Doładuj konto albo popraw metodę płatności na stronie rozliczeń dostawcy |
| 403 | Klucz działa, ale nie ma uprawnień: nieobsługiwany kraj lub region, brak dostępu do tego modelu albo wymagana weryfikacja | Nie | Sprawdź obsługiwane regiony, uprawnienia klucza i ewentualną weryfikację |
| 404 | Błędna nazwa modelu albo adres | Nie | Wybierz inny model albo sprawdź adres |
| 429 | Za dużo żądań w krótkim czasie albo, u niektórych dostawców, puste saldo lub limit wydatków | Czę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, 529 | Awaria lub przeciążenie po stronie dostawcy | Zwykle tak | Spró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.
| Dostawca | Kod przy wyczerpanym saldzie | Treść komunikatu | Oficjalna strona |
|---|---|---|---|
| OpenAI | 429 | credit_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_error | platform.claude.com/docs/en/api/errors (kody); platform.claude.com/docs/en/about-claude/api-credits-for-subscribers (komunikat) |
| Google Gemini | 402 (rozliczenia przedpłacone) | payment_required; 403 może też oznaczać niezapłacone saldo w Cloud Billing | aistudio.google.com/docs/api-errors |
| OpenRouter | 402 | Na koncie lub kluczu API brakuje kredytów (insufficient credits) | openrouter.ai/docs/api-reference/errors |
| DeepSeek | 402 | Insufficient Balance | api-docs.deepseek.com/quick_start/error_codes |
| xAI (Grok) | Nie podano | Żądania są odrzucane, gdy skończą się przedpłacone kredyty | docs.x.ai/console/billing |
| Mistral AI | 402 | Payment required | docs.mistral.ai/resources/error-glossary |
| Groq | Brak w dokumentacji | Groq nalicza opłaty po wykorzystaniu; jego strona błędów nie wymienia błędu salda | console.groq.com/docs/errors |
| Together AI | 402 | Payment Required | docs.together.ai/docs/error-codes |
| Fireworks AI | 402 | Payment Required | docs.fireworks.ai/guides/inference-error-codes |
| MiniMax | Nie podano (kod biznesowy 1008) | insufficient balance | platform.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) | 403 | Arrearage lub isv.OUT_OF_SERVICE (zaległości na koncie) | alibabacloud.com/help/en/model-studio/error-code |
| Kimi (Moonshot AI) | 429 | exceeded_current_quota_error | platform.kimi.ai/docs/api/errors |
| SiliconFlow | Brak w dokumentacji | Nie wymieniono błędu salda | docs.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 pokazuje Oriveo | Co to oznacza | Co 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 sprawdzania | Skopiuj klucz ponownie i zaktualizuj go w ustawieniach tego dostawcy |
| Nieprawidłowy klucz API | Dostawca zwrócił 401 lub 403 | Sprawdź lub wymień klucz; przy 403 sprawdź region i uprawnienia |
| Osiągnięto limit dostawcy | Dostawca 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 limit | Dzisiejszy limit Oriveo Free się wyczerpał; nie ma to nic wspólnego z twoim kluczem | Dodaj własny klucz API albo poczekaj na odnowienie o 00:00 UTC |

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?
Co oznacza błąd 401 przy kluczu API?
Co to jest błąd 402 Payment Required?
Błąd 429 to limit żądań czy brak środków?
Dlaczego mój klucz API OpenAI zwraca insufficient_quota?
Dlaczego nowy klucz API nie działa, choć skopiowano go poprawnie?
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.