Częste błędy połączenia i jak je naprawić

Niemal każdy problem z połączeniem sprowadza się do czterech rzeczy: adresu, klucza, identyfikatora modelu i salda. Zacznij od szybkiego sprawdzenia poniżej, a następnie znajdź swój kod statusu. Cytowane tu treści odpowiedzi to rzeczywiste odpowiedzi API (październik 2026).

Szybkie sprawdzenie#

# 1. The address is reachable — this request needs no key
curl https://api.cheaptokens.dev/v1/models

# 2. The key and the balance work — a tiny request (costs a fraction of a cent)
curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer $CHEAPTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-ai/DeepSeek-V4-Flash-0731", "max_tokens": 5,
       "messages": [{"role": "user", "content": "ping"}]}'

Jeśli pierwsze polecenie zawiedzie, przyczyną może być sieć po twojej stronie, literówka w adresie — albo chwilowa niedostępność samej usługi. Jeśli zawiedzie tylko drugie, znajdź jego kod statusu poniżej. Jeśli oba działają, ale twoje narzędzie nie, porównaj ustawienia narzędzia z tymi dwoma poleceniami.

401 — Nieprawidłowy klucz API#

{"error": {"message": "Invalid API key", "type": "authentication_error"}}

Klienci w stylu Anthropic otrzymują ten sam błąd w swoim formacie:

{"type": "error", "error": {"type": "authentication_error", "message": "Invalid API key"}}

Przyczyny:

• klucz został skopiowany z brakującym znakiem, spacją lub cudzysłowami;
• klucz został zrotowany w panelu — stary już nie działa;
• ustawiono klucz z innej usługi (na przykład OpenAI) zamiast klucza CheapTokens;
• zmienna środowiskowa jest pusta w tym terminalu: echo ${#CHEAPTOKENS_API_KEY} wypisuje jej długość.

Panel pokazuje klucz tylko raz. Jeśli został utracony, naciśnij Rotate, aby uzyskać nowy, i zaktualizuj go wszędzie, gdzie jest używany.

402 — puste saldo lub brak klucza w żądaniu#

API zwraca 402 w dwóch różnych sytuacjach:

1. Saldo zostało wyczerpane. Żądania są opłacane z salda; gdy się skończy, klucz zostaje wstrzymany. Doładuj w panelu, a żądania znów zaczną przechodzić.
2. Żądanie nie ma w ogóle klucza. Jeśli brakuje nagłówka Authorization (lub x-api-key dla klientów w stylu Anthropic), API odpowiada 402 z typem insufficient_funds. Sprawdź, czy twoje narzędzie naprawdę wysyła klucz: styl OpenAI to Authorization: Bearer <key>.

404 — błędny adres#

{"error": {"message": "Invalid URL (GET /v1/chat/completion)", "type": "invalid_request_error", "param": null, "code": null}}

W ścieżce jest literówka — tutaj completion zamiast completions. Inne częste przyczyny:

• Bazowy URL nie ma /v1. Klienci w stylu OpenAI potrzebują https://api.cheaptokens.dev/v1. Bez /v1 żądanie nie trafia do API i zamiast JSON otrzymujesz zwykłą stronę HTML 404.
• /v1 dwa razy. Niektóre klienty same dodają /v1; wtedy bazowy URL musi być adresem głównym, https://api.cheaptokens.dev. Klienci w stylu Anthropic zawsze używają adresu głównego.

400 — nie znaleziono modelu#

{"error": {"message": "Model \"deepseek-v4-flash\" not found. Available: …", "type": "invalid_request_error", "param": "model"}}

Identyfikator modelu musi być pełnym identyfikatorem, wraz z prefiksem przed ukośnikiem: deepseek-ai/DeepSeek-V4-Flash-0731, a nie deepseek-v4-flash. Wielkość liter nie ma znaczenia. Komunikat błędu wymienia dostępne identyfikatory, a pełna lista jest zawsze pod GET /v1/models.

400 wraca także przy nieprawidłowej treści żądania — na przykład przy pustej tablicy messages (messages field is required and must be a non-empty array) lub wiadomości bez role.

413 — żądanie zbyt duże#

Treść żądania jest ograniczona do 16 MB. Agenci mogą go przekroczyć, wrzucając do kontekstu ogromne pliki lub logi. Wysyłaj tylko te części, których model potrzebuje, i skracaj długie wyjście narzędzi.

429 — zbyt wiele żądań#

Jeśli otrzymujesz 429, zwolnij. Odpowiedź zawiera nagłówek Retry-After z liczbą sekund do odczekania. Oficjalne SDK OpenAI ponawiają automatycznie (max_retries); we własnym kodzie odczekaj Retry-After przed kolejną próbą.

503 — model chwilowo niedostępny#

Model może być chwilowo niedostępny; API odpowiada wtedy 503 z typem model_unavailable, a karta modelu na stronie pokazuje „chwilowo niedostępny”. Ponów próbę później lub przełącz pole model na inny model — klucz i adres pozostają takie same.

Długie oczekiwanie i limity czasu#

Modele rozumujące, takie jak zai-org/GLM-5.3-Flash, myślą przed odpowiedzią, więc pierwszy token może zająć trochę czasu. Użyj streamingu lub zwiększ limit czasu klienta — na przykład timeout=120 w SDK OpenAI.