После подключения собственного API к Chatbox ошибки чаще всего относятся не к «сломанной модели», а к четырём классам: не та идентификация, не тот адрес или модель, исчерпан лимит или параллелизм, не проходит сеть и TLS. Сначала классифицировать, потом проверять — гораздо эффективнее, чем переустанавливать клиент.

Ниже разобраны 401, 404 (включая model not found), 429 и сбои соединения, а также обрывы потока, синхронизация настроек на нескольких устройствах и сбор журналов. Названия пунктов меню зависят от вашей версии Chatbox; модели и цены — на странице цены на модели.

Примечание: Chatbox — продукт и товарный знак её правообладателя. Материал носит технический характер и не означает какой-либо подчинённости. Названия полей и значения по умолчанию в разных версиях могут отличаться.

1. Сначала сохраните доказательства, потом классифицируйте

Симптом Частый код или ошибка Первая гипотеза Что проверить
401 invalid_api_key, пустой ответ Ключ или заголовок запроса Полнота ключа и его принадлежность адресу
404 / model not found not_found_error Путь или ID модели Хост, путь API, ID модели
429 Too Many Requests rate_limit_error, insufficient_quota Лимит частоты или баланс Расход, параллелизм, счёт
Failed to fetch / Network Error Без статуса Сеть недоступна DNS, прокси, межсетевой экран, TLS
5xx server_error Сбой апстрима или шлюза Повтор с записью request ID

Перед диагностикой запишите время, версию Chatbox, HTTP-статус, тело ответа и request ID. Без этих данных остаётся гадать; с ними видно, где проблема — в клиенте, сети или сервере.

2. 401: ключ не распознан

401 означает, что сервер не признаёт ключ. Частые причины:

  • при копировании попали пробел, перевод строки или полноширинные символы — выглядит одинаково, но строка другая;
  • лицензионный ключ Chatbox AI вставлен как API-ключ в собственного провайдера;
  • ключ удалён, ротирован или его проект отключён;
  • ключ от поставщика A отправляется на адрес поставщика B;
  • запрос идёт через корпоративный прокси, который возвращает 401 со страницей входа, и в теле приходит HTML вместо JSON.

Сначала убедитесь, что выбран OpenAI-совместимый режим API, затем вставьте ключ заново. Не полагайтесь на «выглядит так же» — проверьте в обход клиента:

export ZSQH_API_KEY="sk-ваш-ключ"

curl -sS "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"ваш-ID-модели","messages":[{"role":"user","content":"Ответь только OK"}]}' \
  -w "\nHTTP %{http_code}\n"

Код 200 и choices означают, что ключ и адрес верны; если 401 остаётся, проблема в копировании, правах или прокси. 403 обычно значит «вас узнали, но эту модель использовать нельзя» — не путайте его с 401 и не меняйте ключи подряд.

3. 404 и model not found: адрес и модель отдельно

404 бывает двух видов: нет пути или нет модели. В первом случае смотрите URL, во втором — ID. Chatbox разделяет хост API и путь API, и самая частая ошибка — дублирование /v1: хост уже заканчивается на /v1, а путь снова содержит /v1/chat/completions, в итоге запрос уходит на /v1/v1/chat/completions.

Критерий один: в итоговом адресе /v1 должен встречаться ровно один раз. Если хост — https://ai.zhongshangqihang.com, путь можно оставить пустым или заполнить по документации текущей версии; если хост — .../v1, путь больше не повторяйте. После изменения сохраните и проверьте кнопкой или curl.

model_not_found не связан с путём. ID модели чувствителен к регистру, суффиксу версии и префиксу поставщика; копируйте его со страницы цены на модели или из консоли. При ручном добавлении проверьте, что тип модели — чат, а отмеченные возможности соответствуют реальным, иначе модель может не появиться или упадёт при первом вызове.

Сбой «Получить список моделей» тоже не обязательно означает ошибку конфигурации. Часть шлюзов не открывает интерфейс списка, и точный ID, введённый вручную, нормально работает.

4. 429: частота, параллелизм и баланс

У 429 два значения: слишком частые запросы или отсутствие квоты. OpenAI-совместимые интерфейсы обычно используют rate_limit_error для первого и insufficient_quota для второго. Оба выглядят как 429, но лечатся противоположно.

  • Слишком часто: снизьте параллелизм, закройте лишние сессии и клиенты; длинный контекст увеличивает расход токенов.
  • Нет квоты: проверьте расход и счёт на шлюзе, пополните баланс или смените ключ; простые повторы не помогут.
  • Если в заголовках есть Retry-After, ждите по нему; если нет — используйте экспоненциальную задержку со случайным разбросом.
  • Не нажимайте в Chatbox «Проверить» и не отправляйте запрос повторно много раз подряд — за короткое время запросы складываются.
  • Один ключ на нескольких устройствах и в нескольких окнах делит общий лимит параллелизма.

Если 429 появляется только в длинных диалогах, сначала сожмите контекст или создайте новую сессию, затем проверьте контекстное окно модели. Параметр «максимальное число сообщений контекста» в настройках можно уменьшить, но он снимает только давление контекста и не заменяет управление расходом и параллелизмом.

5. Сбой соединения: DNS, прокси, SSL и межсетевой экран

Failed to fetch, Network Error и бесконечное вращение означают, что запрос не получил корректного ответа. Сначала проверьте, открывается ли сайт в браузере, затем протестируйте тот же домен через curl. Если curl тоже не работает — проблема в сети или шлюзе; если curl работает, а Chatbox нет — чаще дело в прокси клиента, склейке пути или доверии к сертификату.

  • Корпоративная сеть: межсетевой экран или шлюз безопасности может блокировать незнакомый домен — попросите ИТ добавить его в исключения.
  • Прокси: системный прокси, VPN и переключатель внутри Chatbox могут складываться; оставьте один уровень, а адрес прокси не вписывайте в хост API.
  • TLS: self signed certificate, UNABLE_TO_VERIFY_LEAF_SIGNATURE, истёкший сертификат часто встречаются при корпоративном перехвате; устанавливайте корпоративный корневой сертификат, а не отключайте проверку.
  • Системное время: сильное расхождение ломает проверку сертификата.
  • Мобильная сеть: если результаты в Wi-Fi и сотовой сети различаются, проблема в локальной сети или DNS.

Если ошибка только на одной машине, сравните системный прокси, hosts, DNS и сертификаты — не начинайте с модели.

6. Обрыв потока и «ответ остановился на середине»

Chatbox по умолчанию использует потоковый вывод. Остановка посередине типична в трёх случаях: прокси или шлюз буферизует SSE, соединение простаивает до тайм-аута, апстрим разрывается во время генерации. Выглядит так: первая половина приходит нормально, вторая внезапно заканчивается, либо всё замирает на «печатает».

Начните с отключения потокового вывода (если версия даёт такой переключатель) и повторите тот же вопрос. Если без потока ответ приходит целиком, проблема в цепочке SSE; проверьте буферизацию прокси, тайм-ауты и стабильность сети. Длинные ответы, reasoning-модели и часы пик срабатывают чаще — сократите вывод или повторите позже.

Кроме того, reasoning-модель может долго «думать» перед текстом и выглядеть зависшей. Подождите, затем проверьте неотключённым потоковым запросом, действительно ли ответа нет.

7. Несколько устройств, сессии и синхронизация настроек

Сессии и настройки Chatbox по умолчанию хранятся локально. Если после смены компьютера или телефона истории нет, это обычно не сбой API, а не перенесённые данные. Для миграции используйте экспорт, импорт или копирование, которые предоставляет клиент; возможности зависят от версии.

Более новые версии Chatbox умеют импортировать конфигурацию провайдера в JSON, перенося хост, список моделей и возможности на другое устройство. Но API-ключ всё равно лучше вести отдельно: выдавайте его по устройству или человеку, чтобы при утечке отозвать только один.

Если два устройства ведут себя по-разному, сначала сравните версии, системный прокси и конфигурацию моделей, затем ключи. Не делайте вывод «на другом работает, значит, тут сеть» без проверки.

8. Журналы и доказательства: сформулируйте проблему

Расположение журналов и диагностики в версиях Chatbox различается: где-то есть экспорт в настройках, где-то нужен системный журнал. Независимо от встроенных средств фиксируйте вручную:

  • время (с часовым поясом) и воспроизводимость;
  • версию Chatbox, ОС и сетевую среду;
  • HTTP-статус и полный текст ответа (без ключа);
  • request ID из заголовков;
  • результат curl для того же запроса и сравнение потока с не-потоком.

В обращении замаскируйте ключ, но сохраните ID модели, время и статус. Запись «не подключается» обычно ничего не даёт; с доказательствами большинство проблем классифицируется за один раунд.

9. Фиксированный порядок проверки

  1. Подключитесь к шлюзу через curl и проверьте ключ, хост и модель.
  2. curl не работает: проверьте DNS, прокси, TLS, межсетевой экран и состояние шлюза.
  3. curl работает, Chatbox нет: проверьте тип API, дублирование /v1, ID модели и прокси клиента.
  4. 401 — ключ, 404 — путь и модель, 429 — расход и параллелизм, сбой соединения — сеть и сертификат.
  5. Меняйте за раз одну переменную, сразу повторяйте проверку и записывайте результат.

Ценность порядка в том, что он отделяет проблему клиента от проблемы сервера. Большинство «ошибок Chatbox» в итоге сводится к одной настройке или одному уровню сети.

Если нужны единое управление ключами, расходом и моделями, можно зарегистрироваться в ZSQH AI Gateway; доступные модели и биллинг — на странице цены на модели, цены могут меняться, ориентируйтесь на страницу в момент заказа.

Частые вопросы

Chatbox показывает Failed to fetch — это ошибка ключа?

Не обязательно. Сообщение означает лишь, что клиент не получил ответ, а неверный ключ — только одна из причин. Проверьте тот же хост через curl; если curl тоже не проходит, ищите сеть, прокси и сертификат.

Почему curl работает, а Chatbox не подключается?

Частые причины: прокси клиента, дублирование /v1, неверный тип API, недоверие к системному сертификату или иной способ склейки пути в версии клиента. Сравнивайте итоговый адрес запроса по пунктам.

Восстановится ли 429 само, если повторять?

При ограничении частоты задержка и снижение параллелизма могут помочь; при нехватке квоты повтор не восстановит доступ — нужен баланс или другой ключ. Сначала смотрите тип ошибки в теле ответа.

Если не удалось получить список моделей, можно добавить вручную?

Да. Часть шлюзов не открывает интерфейс списка, и точный ID, введённый вручную, работает в диалоге — при условии, что ID модели, тип API и хост верны.

Синхронизируются ли сессии и настройки при смене устройства?

Сессии по умолчанию хранятся локально и не всегда синхронизируются. Используйте экспорт и импорт; новые версии умеют импортировать JSON провайдера, но API-ключ лучше ввести заново и вести отдельно.

Полезное чтение: