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

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

Код	Сообщение	Причина	Решение
401	Недействительный API-ключ	Ключ отсутствует, имеет неверный формат или отозван	Проверьте заголовок `Authorization: Bearer sk-...`. Убедитесь, что ключ активен в Панели управления → API-ключи. Ключи начинаются с `sk-`.
404	Конечная точка не найдена	URL запроса не соответствует ни одному API-эндпоинту	Проверьте путь запроса по справочнику API. Примечание: ошибки «модель не найдена» возвращаются как `503` с кодом `model_not_found` — см. Коды ошибок.
429	Превышен лимит запросов / недостаточно квоты	Слишком много запросов в текущем окне или исчерпан баланс аккаунта / API-ключа	Для ограничения запросов реализуйте экспоненциальную задержку с джиттером. Если сообщение об ошибке упоминает квоту или баланс (например, `insufficient_user_quota`), пополните баланс в Панели управления → Биллинг вместо повторных попыток. См. Лимиты запросов.
500	Внутренняя ошибка сервера	Проблема на стороне TokSpan	Повторите с экспоненциальной задержкой. Если проблема сохраняется >5 мин, проверьте страницу статуса.
502	Ошибка шлюза	Upstream-провайдер недоступен или превышено время ожидания	Повторите — автоматическое переключение должно направить запрос на резервного провайдера, обслуживающего ту же модель. Если проблема сохраняется, обратитесь в поддержку.
503	Сервис недоступен / модель не найдена	Временная перегрузка или модель недоступна для вашего ключа	Повторите с задержкой — не полагайтесь на заголовок `Retry-After`. Если ошибка содержит код `model_not_found`, проверьте название модели в каталоге моделей; названия чувствительны к регистру. Проверьте страницу статуса.

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

Ошибки "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-провайдер может быть медленным — попробуйте более быструю или лёгкую модель

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

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

Действителен ли ваш 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":"MODEL_NAME","messages":[{"role":"user","content":"Hi"}]}'
```
Если возвращается 401, проблема в ключе. Если возвращается 200 с содержимым, ваш ключ и базовый URL корректны.
Правильно ли указано название модели? — Проверьте каталог моделей. Частая ошибка: использование "gpt4" вместо "gpt-4o".
Есть ли у вас кредиты? — Проверьте Панель управления → Биллинг. Баланс должен быть > $0.
Превышен ли лимит запросов или закончилась квота? — При ответе 429 снизьте параллельность и повторите с экспоненциальной задержкой (используйте заголовок Retry-After, если он есть). Если ошибка упоминает квоту/баланс, проверьте кредиты в Панели управления → Биллинг.
Работает ли сервис? — Проверьте страницу статуса 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 часов.