Устранение неполадок — Документация TokSpan

Распространённые коды ошибок

Код	Сообщение	Причина	Решение
401	Недействительный API-ключ	Ключ отсутствует, имеет неверный формат или отозван	Проверьте заголовок `Authorization: Bearer sk-...`. Убедитесь, что ключ активен в Панели управления → API-ключи. Ключи начинаются с `sk-`.
402	Недостаточный баланс	Баланс аккаунта равен нулю или отрицательный	Пополните баланс в Панели управления → Биллинг. Включите автопополнение для продакшен-ключей.
404	Модель не найдена	ID модели не существует или указан с ошибкой	Проверьте название модели по списку доступных моделей. Названия моделей чувствительны к регистру.
429	Превышен лимит запросов	Слишком много запросов или токенов в текущем окне	Проверьте заголовки `x-ratelimit-remaining-*`. Реализуйте экспоненциальную задержку между повторами. См. Лимиты запросов.
500	Внутренняя ошибка сервера	Проблема на стороне TokSpan	Повторите с экспоненциальной задержкой. Если проблема сохраняется >5 мин, проверьте страницу статуса.
502	Ошибка шлюза	Upstream-провайдер недоступен или превышено время ожидания	Повторите — автоматическое переключение должно направить запрос на резервную модель. Если проблема сохраняется, настройте цепочку переключения.
503	Сервис недоступен	Временная перегрузка	Подождите и повторите через время, указанное в заголовке `Retry-After`. Проверьте страницу статуса.

Проблемы с соединением

Ошибки "Connection refused" / "Name resolution failed"

Проверьте базовый URL: https://api.tokspan.com/v1 (обратите внимание: https://, а не http://)
Проверьте, что ваш брандмауэр / прокси разрешает исходящий HTTPS на порт 443
DNS-тест: nslookup api.tokspan.com должен вернуть IP-адрес
Если вы находитесь в регионе с ограниченным доступом к интернету, возможно, потребуется собственный хостинг

Ошибка SSL-сертификата (SSL Certificate Error)

Убедитесь, что корневые сертификаты вашей системы актуальны
Проверьте точность системных часов (SSL-сертификаты чувствительны ко времени)
Мы используем сертификаты Let's Encrypt — они доверены всеми основными ОС

Тайм-аут запроса (Request Timeout)

Тайм-аут по умолчанию зависит от SDK. Установите явно: минимум 60 с для чата, 120 с для длительных генераций
Используйте потоковую передачу (stream: true) — вы будете получать токены без ожидания полного ответа
Если тайм-ауты происходят постоянно с определённой моделью, upstream-провайдер может быть медленным — попробуйте другую модель или добавьте суффикс -fast

Быстрый диагностический чек-лист

Пройдите по этим пунктам перед отправкой запроса в поддержку:

Действителен ли ваш API-ключ? — Проверьте с помощью минимального curl-запроса:
```
curl -X POST "https://api.tokspan.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hi"}]}'
```
Если возвращается 401, проблема в ключе. Если возвращается 200 с содержимым, ваш ключ и базовый URL корректны.
Правильно ли указано название модели? — Проверьте каталог моделей. Частая ошибка: использование "gpt4" вместо "gpt-4o".
Есть ли у вас кредиты? — Проверьте Панель управления → Биллинг. Баланс должен быть > $0.
Не превышен ли лимит запросов? — Проверьте заголовки ответа x-ratelimit-remaining-requests. Если значение 0, дождитесь сброса окна.
Работает ли сервис? — Проверьте страницу статуса API на наличие текущих инцидентов.

Проблемы, специфичные для SDK

Python (SDK openai)

ModuleNotFoundError: openai → pip install openai
openai.APIError / APIConnectionError → Проверьте сетевое подключение. Попробуйте curl напрямую, чтобы изолировать проблему SDK от проблемы сети.
Прокси: Установите http_client=httpx.Client(proxy="http://proxy:8080") при использовании корпоративного прокси

Node.js (SDK openai)

Cannot find module 'openai' → npm install openai
ERR_MODULE_NOT_FOUND → Используйте import с ESM или require('openai') с CJS
fetch is not defined (Node < 18) → Обновите Node до 18+ или используйте полифил globalThis.fetch

Всё ещё не получается?

При обращении в поддержку укажите следующее — это значительно ускорит решение:

Email вашей учётной записи
ID запроса из ответа с ошибкой (поле id)
Полное тело ответа с ошибкой и HTTP-код статуса
Модель, которую вы вызываете, и минимальный фрагмент кода, воспроизводящий проблему
Версия вашего SDK (pip show openai / npm list openai)

Напишите нам на support@tokspan.com — мы отвечаем в течение 24 часов.