Ошибки и лимиты
Ошибку на запрос возвращает либо платформа, либо сама нейросеть. Различать их важно: ошибку платформы устраняет администратор инсталляции, ошибку нейросети – разработчик запроса по документации соответствующего сервиса.
Источник ошибки
Различие видно по форме тела ответа.
Платформа отвечает объектом, где error – строка:
{"error": "invalid endpoint"}
При отказе на этапе проверки токена – объектом с полями code и message:
{"code":401,"message":"invalid token"}
Нейросеть отвечает своим телом, и платформа передает его без изменений. Ее код ответа становится кодом HTTP-ответа. Например, ответ в формате OpenAI, где error – объект, пришел не от платформы:
{"error": {"message": "...", "type": "invalid_request_error"}}
Коды ответов
| Код | Тело | Причина | Что делать |
|---|---|---|---|
400 | {"error": "nexus not found"} | Нексус не указан ни полем model, ни заголовком X-NEXUS. | Укажите нексус. |
400 | {"error": "nexus \"<имя>\" not found"} | Нексуса не существует, он не выдан вашей инсталляции или срок его доступности истек. | Сверьте имя со списком доступных нексусов. |
400 | {"error": "invalid endpoint"} | Путь запроса не совпадает с конечной точкой нексуса. | Уточните путь нексуса у администратора инсталляции. |
400 | {"error": "invalid endpoint"} | В запросе через конверт указан несуществующий нексус или нексус, не выданный вашей инсталляции. | Сверьте имя со списком доступных нексусов. |
400 | {"error": "parse request data: ..."} | Тело запроса повреждено или передано с неподдерживаемым типом содержимого. | Передавайте тело в формате JSON с заголовком Content-Type: application/json. |
400 | {"error": "the `form_name` field is required for each file"} | В запросе через конверт у файла не заполнено поле form_name. | Заполните поле для каждого файла. |
401 | {"code":401,"message":"..."} | Токен не передан, не найден или отозван. | Читайте подробнее в статье Аутентификация. |
403 | {"code":403,"message":"token blocked"} | Токен заблокирован администратором или по исчерпанию квоты. | Обратитесь к администратору инсталляции. |
404 | 404 page not found | Путь не совпал ни с одним маршрутом платформы. | Проверьте путь запроса. |
405 | – | Метод запроса не поддерживается. | Используйте GET или POST. |
408 | {"error": "nexus <имя>: Read timed out. (read timeout=<N>)"} | Нейросеть не ответила за время ожидания, заданное в настройке нексуса. | Повторите запрос или сократите его. Читайте подробнее в статье Обращение к нексусу. |
429 | {"error": "the nexus exceeded RPM limit"} | Превышено число запросов в минуту. | Повторите запрос в следующую минуту. |
429 | {"error": "the nexus exceeded RPD limit"} | Превышено число запросов в сутки. | Повторите запрос на следующие сутки. |
500 | {"code":500,"message":"token service error"} | Сбой хранилища токенов. | Повторите запрос, при повторении обратитесь в поддержку. |
500 | {"error": "Neural network error"} | Ответ от нейросети не получен, в том числе из-за истекшего сертификата нейросети или сертификата, выпущенного на другое имя хоста. | Обратитесь к администратору инсталляции: если причина в сертификате нейросети, сертификат нужно заменить. |
502 | {"error": "service app is unavailable"} | Ответ от нейросети не получен: запрос к службе завершился ошибкой, не связанной с истечением времени ожидания. | Обратитесь в поддержку. Повторный запрос может дважды учесться в потреблении по лицензии: первое обращение могло дойти до нейросети. |
502 | {"error": "tls error: ..."} | Сертификат нейросети выпущен центром сертификации, которому платформа не доверяет, например корпоративным центром. Запрос до нейросети не дошел. Платформа повторяет запрос четыре раза с паузами 0, 5, 10 и 15 секунд, поэтому ответ приходит примерно через 30 секунд. Если для нексуса задана конфигурация в поле Bypass, после этого запрос выполняется через нее и задержка увеличивается. | Обратитесь к администратору инсталляции: корневой сертификат центра сертификации добавляется в доверенные при развертывании инфраструктуры Middleware. |
503 | {"code":503,"message":"..."} | Служба проверки токенов недоступна. | Повторите запрос позже. |
504 | HTML-страница 504 Gateway Time-out или {"error": "service app timed out"}. Тело зависит от настроек установки платформы, поэтому распознавайте ответ по коду. | Нейросеть не начала отвечать за 1800 секунд. Такое возможно, если время ожидания нексуса больше 1800 секунд. Если для нексуса задана конфигурация в поле Bypass, с 1800 секундами сравнивается сумма времени ожидания обеих конфигураций. | Сократите запрос или уменьшите параметр, ограничивающий длину ответа, например max_tokens. Повторный запрос может дважды учесться в потреблении по лицензии: первое обращение могло дойти до нейросети. |
Нексус, заблокированный администратором, отвечает телом {"error": "the nexus `<имя>` is blocked, description: `<текст>`"}. Код ответа задается в настройке блокировки и может быть любым. Распознавайте такой ответ по подстроке is blocked в теле, а не по коду.
Два ответа со словами not found различаются по наличию имени нексуса в кавычках: без имени – нексус не указан в запросе, с именем – нексус указан, но недоступен. Первое исправляется в коде, второе – обращением к администратору.
Платформа не возвращает собственный идентификатор запроса. Чтобы обращение можно было найти при разборе, передавайте заголовок X-SESSION-ID и сохраняйте его значение у себя.
Ограничения по частоте запросов
Число обращений к нексусу ограничено двумя счетчиками: запросов в минуту и запросов в сутки. При превышении платформа возвращает ответ 429, не обращаясь к нейросети.
Счетчики привязаны к календарным минуте и суткам, а не к скользящему окну: минутный счетчик обнуляется с началом следующей минуты, суточный – с началом следующих суток.
Действующее ограничение складывается из трех уровней: лицензии, потребителя и отдельного нексуса. К запросу применяется итоговое значение, и по ответу нельзя определить, на каком уровне сработало ограничение. Читайте подробнее в статьях Лицензии и Потребители.
Заголовков с остатком лимита и временем до его сброса платформа не возвращает: ни Retry-After, ни RateLimit-* в ответе нет. Действующие значения уточняйте у администратора инсталляции. После ответа 429 повторяйте запрос с нарастающей паузой.
Расход кредитов
Потребление по лицензии платформа считает в кредитах по правилам, которые администратор инсталляции задал для нексуса. Израсходованные кредиты видны администратору в отчетах. Читайте подробнее в статье Мониторинг потребления.
Если администратор включил для нексуса возврат кредитов, расход обращения приходит в теле успешного ответа в формате JSON – в поле, которое задал администратор, например usage.credits. Значение – целое число кредитов. Путь к полю уточняйте у администратора инсталляции. Если биллинг нексуса отключен, этого поля в ответе нет. Читайте подробнее о расчете в статье Расчет расхода.
Остальные поля объекта usage принадлежат нейросети и показывают израсходованные ею токены модели. Это не кредиты: потребление по лицензии платформа считает отдельно. Администратор может убрать из ответа расход токенов модели. Тогда в объекте usage остается только поле с кредитами, если путь к нему задан внутри usage.
В потреблении по лицензии учитываются обращения, на которые нейросеть ответила успешно. Запросы, отклоненные по ограничению частоты, и ответы с ошибкой, включая 408, не учитываются – повтор такого запроса квоту не расходует. Исключение – ответы 502 и 504: обращение могло дойти до нейросети, завершиться у нее успешно и учесться в потреблении, хотя клиент получил ошибку.
Когда квота токена исчерпана, токен блокируется автоматически, и все последующие запросы получают ответ 403. Снять такую блокировку может администратор инсталляции, увеличив квоту. Читайте подробнее в статье API-токены.