Назад до блогу

Вирішення проблемПосібник

Поширені помилки підключення та як їх виправити

Що означають 401, 402, 400, 404, 413, 429 і 503, коли ви підключаєтеся до API CheapTokens, як виглядають відповіді та як виправити кожну з них.

Автор: CheapTokens TeamОпубліковано 3 хв читання

Список кодів стану HTTP 401, 402, 400, 404 і 429 з короткими поясненнями в терміналі
На цій сторінці
  1. Швидка перевірка
  2. 401 — недійсний API-ключ
  3. 402 — порожній баланс або відсутність ключа в запиті
  4. 404 — неправильна адреса
  5. 400 — модель не знайдено
  6. 413 — запит завеликий
  7. 429 — забагато запитів
  8. 503 — модель тимчасово недоступна
  9. Довгі очікування та тайм-аути

Майже кожна проблема з підключенням зводиться до чотирьох речей: адреси, ключа, ідентифікатора моделі та балансу. Почніть із швидкої перевірки нижче, а потім знайдіть свій код стану. Наведені тут тіла відповідей — це фактичні відповіді API (жовтень 2026).

Швидка перевірка#

bash
# 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"}]}'

Якщо перша команда не працює, причиною може бути мережа на вашому боці, друкарська помилка в адресі — або тимчасова недоступність самого сервісу. Якщо не працює лише друга, знайдіть її код стану нижче. Якщо обидві працюють, а ваш інструмент — ні, порівняйте налаштування інструмента з цими двома командами.

401 — недійсний API-ключ#

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

Клієнти в стилі Anthropic отримують ту саму помилку у своєму форматі:

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

Причини:

  • ключ скопійовано з пропущеним символом, пробілом або лапками;
  • ключ було перегенеровано в панелі керування — старий більше не працює;
  • замість ключа CheapTokens встановлено ключ від іншого сервісу (наприклад, OpenAI);
  • змінна середовища порожня в цьому терміналі: echo ${#CHEAPTOKENS_API_KEY} виводить її довжину.

Панель керування показує ключ лише один раз. Якщо його втрачено, натисніть Rotate, щоб отримати новий, і оновіть його всюди, де він використовується.

402 — порожній баланс або відсутність ключа в запиті#

API повертає 402 у двох різних ситуаціях:

  1. Баланс вичерпано. Запити оплачуються з балансу; коли він закінчується, ключ призупиняється. Поповніть баланс у панелі керування, і запити знову проходитимуть.
  2. У запиті взагалі немає ключа. Якщо заголовок Authorization (або x-api-key для клієнтів у стилі Anthropic) відсутній, API відповідає 402 з типом insufficient_funds. Перевірте, що ваш інструмент справді надсилає ключ: стиль OpenAI — це Authorization: Bearer <key>.

404 — неправильна адреса#

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

У шляху є друкарська помилка — тут completion замість completions. Інші поширені причини:

  • У базовій URL немає /v1. Клієнтам у стилі OpenAI потрібен https://api.cheaptokens.dev/v1. Без /v1 запит не потрапляє до API, і ви отримуєте звичайну HTML-сторінку 404 замість JSON.
  • /v1 двічі. Деякі клієнти додають /v1 самостійно; тоді базова URL має бути кореневою, https://api.cheaptokens.dev. Клієнти в стилі Anthropic завжди використовують кореневу адресу.

400 — модель не знайдено#

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

Ідентифікатор моделі має бути повним, включно з префіксом перед слешем: deepseek-ai/DeepSeek-V4-Flash-0731, а не deepseek-v4-flash. Великі чи малі літери не мають значення. Повідомлення про помилку перелічує доступні ідентифікатори, а повний список завжди доступний за адресою GET /v1/models.

400 також повертається за некоректного тіла запиту — наприклад, порожнього масиву messages (messages field is required and must be a non-empty array) або повідомлення без role.

413 — запит завеликий#

Тіло запиту обмежено 16 МБ. Агенти можуть перевищити це, додаючи до контексту величезні файли або логи. Надсилайте лише ті частини, які потрібні моделі, і скорочуйте довгий вивід інструментів.

429 — забагато запитів#

Якщо ви отримуєте 429, сповільніться. Відповідь містить заголовок Retry-After із кількістю секунд для очікування. Офіційні SDK OpenAI повторюють спробу автоматично (max_retries); у власному коді зачекайте Retry-After перед наступною спробою.

503 — модель тимчасово недоступна#

Модель може бути тимчасово недоступною; тоді API відповідає 503 з типом model_unavailable, а картка моделі на сайті показує "тимчасово недоступна". Повторіть спробу пізніше або змініть поле model на іншу модель — ключ і адреса залишаються тими самими.

Довгі очікування та тайм-аути#

Моделі міркування, як-от zai-org/GLM-5.3-Flash, думають перед відповіддю, тож перший токен може з'явитися не одразу. Використовуйте потокове передавання або збільште тайм-аут клієнта — наприклад, timeout=120 в SDK OpenAI.

Теги: