Справочник

Ошибки и деградация

Шлюз различает три ситуации: ошибку запроса или сервиса (HTTP-код 4xx или 5xx), неполный результат (код 200 с отметками available: false и записями в gaps) и деградацию ответа модели (код 200 с degraded: true). Для двух последних код ответа – 200, поэтому машинный клиент проверяет поля ответа, а не только код.

Коды ответов

Код	Когда	`detail`	Повторять
401	Ключ не передан, неверен, отозван или истек его срок	`Невалидный или отсутствующий API-ключ`; заголовок `WWW-Authenticate: ApiKey`	Нет: проверьте ключ и заголовок
403	Запрос с ключом API к `/v1/answer` или к `/v1/research` с `agent_search: true` или `research_mode: "loop"`: ответы и режимы с ИИ-агентом LexaAI по ключу недоступны	`Ответы ИИ-агента LexaAI недоступны по ключу API. Для своего агента используйте /v1/research, /v1/search и /v1/practice/*; ответы ИИ-агента LexaAI доступны в чате app.lexaai.ru` или `Режимы с ИИ-агентом LexaAI (agent_search, research_mode=loop) недоступны по ключу API`	Нет: используйте `/v1/research` в режиме по умолчанию, `/v1/search` или `/v1/practice/*`, см. Авторизация и лимиты
404	Документа с таким `doc_key` нет (`/v1/practice/documents/{doc_key}`) или путь не существует	`Документ практики не найден` или `Not Found`	Нет
422	Тело или параметры не соответствуют схеме; недопустимое значение фильтра; синтаксическая ошибка языка запросов; лишнее поле в `/v1/practice/list` и `/v1/practice/facets`; неизвестный слой в `/v1/search`; неверный курсор	строка или массив, см. ниже	Нет: исправьте запрос
429	Превышено ограничение частоты плана или лимит по IP-адресу для запросов без ключа; месячных лимитов нет	причина, см. Авторизация и лимиты	Через `Retry-After` секунд
500	Необработанная ошибка шлюза	`Внутренняя ошибка шлюза`	Да, с паузой
502	Только `/v1/practice/documents/{doc_key}`: слой практики вернул ошибку или некорректный ответ	причина	Да, с паузой
503	Слой практики недоступен (`/v1/practice/*`); сервис подготовки ответа не настроен (`/v1/answer`); хранилище ключей временно недоступно	причина	Да, с паузой

Ошибка 503 хранилища ключей (Хранилище ключей временно недоступно) не означает, что ключ отозван: отозванный ключ получает 401.

Формат detail

Ошибки шлюза и слоев возвращают строку:

JSON

{"detail": "недопустимое значение instance='кассация'; допустимо: первая, апелляция, первая кассация, вторая кассация"}

Ошибки проверки тела по схеме возвращают массив с местом ошибки:

JSON

{
  "detail": [
    {
      "type": "string_too_short",
      "loc": ["body", "question"],
      "msg": "String should have at least 5 characters",
      "input": "Как?",
      "ctx": {"min_length": 5}
    }
  ]
}

Обрабатывайте оба варианта. Тексты detail предназначены для человека и могут уточняться: не стройте на них логику клиента, кроме различения причин 429.

Неполный результат: available и gaps

В /v1/search недоступный слой приходит как {"available": false, "error": "…"}, второй слой отвечает как обычно; код ответа – 200.
В /v1/research и /v1/answer сбой слоя не прерывает работу: слой помечается available: false, причина добавляется в gaps.
gaps перечисляет и то, что не является сбоем: норму вне корпуса, отсутствие редакции на дату, срез корпуса практики, пустую выдачу по фильтрам.
Пустая выдача при валидном запросе – ответ «в корпусе нет», а не ошибка.

Деградация ответа: degraded

Если сервис подготовки ответа недоступен или не уложился в срок, /v1/answer возвращает код 200, answer: null, degraded: true, причину в degradation.reason и найденные материалы с текстом в materials. Причины и их смысл – в разделе Ответ по досье. Отказ по существу – answer: null без поля degraded – означает, что материалов для ответа не нашлось; это не сбой.

Повторы

Ситуация	Что делать
`500`, `502`, `503`, сетевая ошибка в `/v1/search`, `/v1/practice/*`, `/v1/research` без агента, `GET`-эндпоинтах	Повторить с нарастающей паузой, например через 2, 4 и 8 секунд, не более трех раз. Эти запросы не меняют данных, но каждый повтор списывает единицу
`429`	Ждать `Retry-After` секунд
`degraded: true` с причиной `no_healthy_route`	Канал к сервису подготовки ответа недоступен; повтор имеет смысл не раньше чем через несколько минут. Найденные материалы уже есть в `materials`
`401`, `403`, `404`, `422`	Не повторять без изменения запроса

Чтобы не терять результат долгого запроса, задавайте таймаут чтения с запасом – см. таблицу в разделе Быстрый старт.