Диагностика
Ошибки и безопасность
Сначала определите, был ли запрос принят и начался ли ответ. Повтор после обрыва может создать вторую генерацию и повторно потратить квоту.
Формат ошибки шлюза
{
"error": {
"message": "The employee token is missing, unknown or revoked.",
"type": "authentication_error"
}
}Проверяйте HTTP status и error.type, не разбирайте английский текст message как машинный код. После начала SSE HTTP status уже может быть 200: в событии ошибки переведённого Chat-потока проверяйте error.type: upstream_error, error.code (incomplete_response, provider_overloaded при перегрузке 503 или provider_rate_limited при отказе 429) и вложенный error.status. Ошибки нативного API поставщика могут иметь другой формат.
Типовые ошибки
| HTTP / error.type | Ваше действие |
|---|---|
| 401 · authentication_error | Проверьте токен и заголовок авторизации. Если токен отозван, запросите новый. |
| 403 · employee_disabled | Доступ сотрудника заблокирован. Обратитесь к администратору. |
| 404 · model_unavailable | Получите свежий /v1/models. Выберите доступный id или попросите назначить подключение. |
| 400 · unsupported_model | Выберите протокол, который поддерживает семейство модели. |
| 400 · invalid_request | Проверьте JSON, model, сообщения и обязательные поля выбранного протокола. |
| 413 · request_too_large | Уменьшите тело запроса, историю или объём изображений. |
| 429 · provider_quota_exhausted | Дождитесь сброса квоты. Учитывайте Retry-After, не повторяйте запрос сразу. Этот тип ставят проверки квот Claude и GPT; 429 от самого GLM и обычные троттлинги проходят как есть, с форматом ошибки поставщика. |
| 503 · gateway_busy / provider_busy | Шлюз или подключение перегружены. Подождите и повторите, если ответ ещё не начался. |
| 409 · route_changed / ambiguous_route | Обновите список моделей. Если проблема повторяется, сообщите администратору. |
| 502 · provider_auth_failed | Подписку нужно переподключить. Это делает администратор. |
| 502/503 · upstream_unavailable | Возможен временный сбой или проблема настройки. При повторении обратитесь к администратору. |
| 4xx/5xx · upstream_error | Отказ поставщика на переведённом Chat-пути сохраняет его HTTP-статус (возможны 400, 401, 429, 500), а error.status дублирует его в теле. Если SSE уже начался, ошибка приходит внутри потока, не новым HTTP-статусом. |
Это основные ошибки, не полный перечень ответов внешних LLM. Шлюз не переключает исчерпавшую квоту подписку на чужое подключение.
Когда повторять запрос
- При 401, 403 и ошибках параметров сначала исправьте причину.
- При 429 соблюдайте Retry-After или дождитесь сброса квоты.
- При временном отказе до начала ответа допустим отложенный повтор.
- Если уже получен текст или вызов инструмента, сохраните частичный результат и решите вручную, нужен ли повтор. Внешнее действие инструмента может уже выполниться.
HTTP 200 в начале SSE не гарантирует завершение. Проверяйте терминальное событие протокола, а не только статус соединения.
Безопасность токена
- Храните токен в окружении или секретном хранилище клиента, не в исходном коде.
- Не отправляйте токен, Authorization, cookies или ключи провайдера в диагностику.
- Если токен утёк, попросите администратора отозвать его и выпустить новый.
- Отзыв одного токена не отзывает остальные. Блокировка сотрудника запрещает новые запросы по всем его токенам.
- Уже выполняющиеся запросы при отзыве токена или блокировке не прерываются.
Содержимое вашего запроса отправляется выбранному LLM-провайдеру. Не передавайте данные, которые нельзя обрабатывать у этого поставщика.
Что сообщить администратору
Время ошибки с часовым поясом, название и версию клиента, модель, путь API, HTTP status, error.type и факт начала потока. Если есть ID запроса, приложите его. Не прикладывайте токен или конфиденциальное содержимое разговора.