Ошибки и лимиты
Ошибку на запрос возвращает либо платформа, либо сама нейросеть. Различать их важно: ошибку платформы устраняет администратор инсталляции, ошибку нейросети – разработчик запроса по документации соответствующего сервиса.
Источник ошибки
Различие видно по форме тела ответа.
Платформа отвечает объектом, где 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":"blocked by Admin: <причина>"} | Токен заблокирован администратором платформы. Причина указывается после двоеточия, если администратор ее задал. | Обратитесь к администратору инсталляции. |
403 | {"code":403,"message":"blocked by MWAdmin: <причина>"} | Токен заблокирован администратором инфраструктуры. Причина указывается после двоеточия, если администратор ее задал. | Обратитесь к администратору инсталляции. |
403 | {"code":403,"message":"quota exceeded"} | Потребление токена достигло значения правила квоты. | Обратитесь к администратору инсталляции. |
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: `<текст>`"}. Нексус блокируется:
- по квоте – код ответа
429, вdescriptionуказана причина:The license has no active quota– у лицензии нет действующей квоты;Quota exceeded– квота лицензии исчерпана в режиме контроля лицензии Строгий;Quota limit exceeded,Quota limit for nexus exceeded– потребление лицензии достигло значения правила квоты уровня Лицензия;Consumer quota limit exceeded,Consumer quota limit for nexus exceeded– потребление потребителя достигло значения его правила квоты;
- администратором – код ответа задается при блокировке и может быть любым.
Распознавайте такой ответ по подстроке is blocked в теле, а не по коду.
Два ответа со словами not found различаются по наличию имени нексуса в кавычках: без имени – нексус не указан в запросе, с именем – нексус указан, но недоступен. Первое исправляется в коде, второе – обращением к администратору.
Платформа не возвращает собственный идентификатор запроса. Чтобы обращение можно было найти при разборе, передавайте заголовок X-SESSION-ID и сохраняйте его значение у себя.
Ограничения по частоте запросов
Число обращений к нексусу ограничено двумя счетчиками: запросов в минуту и запросов в сутки. При превышении платформа возвращает ответ 429, не обращаясь к нейросети.
Счетчики привязаны к календарным минуте и суткам, а не к скользящему окну: минутный счетчик обнуляется с началом следующей минуты, суточный – с началом следующих суток.
Значения счетчиков задаются правилами лимитов на уровне лицензии или потребителя, для всех нексусов или для отдельного нексуса. Счетчики ведутся по каждому нексусу отдельно, в том числе когда правило задано для всех нексусов. К запросу применяется самое узкое подходящее правило, и по ответу нельзя определить, какое правило сработало. Если квота лицензии исчерпана, а режим контроля лицензии – Ограничение скорости, действуют пониженные затухающие лимиты, если администратор задал их в правилах. Читайте подробнее в статье Правила лимитов.
Заголовков с остатком лимита и временем до его сброса платформа не возвращает: ни Retry-After, ни RateLimit-* в ответе нет. Действующие значения уточняйте у администратора инсталляции. После ответа 429 повторяйте запрос с нарастающей паузой.
Расход кредитов
Потребление по лицензии платформа считает в кредитах по правилам, которые администратор инсталляции задал для нексуса. Израсходованные кредиты видны администратору на странице потребления. Читайте подробнее в статье Мониторинг потребления.
Если администратор включил для нексуса возврат кредитов, расход обращения приходит в теле успешного ответа в формате JSON – в поле, которое задал администратор, например usage.credits. Значение – целое число кредитов. Путь к полю уточняйте у администратора инсталляции. Если биллинг нексуса отключен, этого поля в ответе нет. Читайте подробнее о расчете в статье Расчет расхода.
Остальные поля объекта usage принадлежат нейросети и показывают израсходованные ею токены модели. Это не кредиты: потребление по лицензии платформа считает отдельно. Администратор может убрать из ответа расход токенов модели. Тогда в объекте usage остается только поле с кредитами, если путь к нему задан внутри usage.
В потреблении по лицензии учитываются обращения, на которые нейросеть ответила успешно. Запросы, отклоненные по ограничению частоты, и ответы с ошибкой, включая 408, не учитываются – повтор такого запроса квоту не расходует. Исключение – ответы 502 и 504: обращение могло дойти до нейросети, завершиться у нее успешно и учесться в потреблении, хотя клиент получил ошибку.
Когда потребление токена достигает значения правила квоты, токен блокируется автоматически, и все последующие запросы получают ответ 403 с текстом quota exceeded. Блокировка снимается, когда значение правила увеличивают, правило удаляют или исключают из него токен либо начинается новая квота лицензии. Читайте подробнее в статье API-токены.