Ошибки и лимиты
Ошибку на запрос возвращает либо платформа, либо сама нейросеть. Различать и х важно: ошибку платформы устраняет администратор инсталляции, ошибку нейросети – разработчик запроса по документации соответствующего сервиса.
Как отличить ошибку платформы от ошибки нейросети
Различие видно по форме тела ответа.
Платформа отвечает объектом, где 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"} | Сбой хранилища токенов. | Повторите запрос, при повторении обратитесь в поддержку. |
502 | {"error": "service app is unavailable"} | Ответ от нейросети не получен: запрос к службе завершился ошибкой, не связанной с истечением времени ожидания. | Обратитесь в поддержку. Повторяйте запрос осознанно: обращение могло дойти до нейросети и попасть в расход лицензии. |
503 | {"code":503,"message":"..."} | Служба проверки токенов недоступна. | Повторите запрос позже. |
504 | HTML-страница 504 Gateway Time-out или {"error": "service app timed out"}. Тело зависит от настроек установки платформы, распознавайте ответ по коду | Нейросеть не начала отвечать за 1800 секунд. Такое возможно, если время ожидания нексуса, а при заданной в поле Bypass конфигурации – сумма времени ожидания двух конфигураций, больше 1800 секунд. | Сократите запрос или уменьшите параметр, ограничивающий длину ответа, например max_tokens. Повторяйте запрос осознанно: обращение могло дойти до нейросети и попасть в расход лицензии. |
Нексус, заблокированный администратором, отвечает телом {"error": "the nexus `<имя>` is blocked, description: `<текст>`"}. Код ответа в этом случае задается в настройке блокировки и может быть любым, поэтому распознавайте такой ответ по подстроке is blocked в теле, а не по коду.
Два ответа со словами not found различаются по наличию имени нексуса в кавычках: без имени – нексус не указан в запросе, с именем – нексус указан, но недоступен. Первое исправляется в коде, второе – обращением к администратору.
Ответ 408 приходит, когда нейросеть не успела ответить за время, отведенное настройкой нексуса. Читайте подробнее в статье Обращение к нексусу.
Платформа не возвращает собственный идентификатор запроса. Чтобы обращение можно было найти при разборе, передавайте заголовок X-SESSION-ID и сохраняйте его значение у себя.
Ограничения по частоте запросов
Число обращений к нексусу ограничено двумя счетчиками: запросов в минуту и запросов в сутки. При превышении платформа возвращает ответ 429, не обращаясь к нейросети.
Счетчики привязаны к календарным минуте и суткам, а не к скользящему окну: минутный счетчик обнуляется с началом следующей минуты, суточный – с началом следующих суток.
Действующее ограничение складывается из трех уровней – лицензии, потребителя и отдельного нексуса, – а до запроса доходит уже итоговое значение. Определить по ответу, какой из уровней сработал, нельзя. Читайте подробнее в статье Лицензии и в статье Потребители.
Заголовков с остатком лимита и временем до его сброса платформа не возвращает: ни Retry-After, ни RateLimit-* в ответе нет. Действующие значения уточняйте у администратора инсталляции, а повтор после 429 стройте с нарастающей паузой.
Расход токенов
Расход лицензии считается платформой в А-токенах. В ответе API он не передается: израсходованные А-токены видны администратору инсталляции в отчетах. Читайте подробнее в статье Мониторинг потребления.
Поле usage, если оно есть в ответе, принадлежит нейросети и показывает израсходованные ею токены модели. Это не А-токены: расход лицензии считается платформой отдельно.
В расход лицензии попадают обращения, на которые нейросеть ответила успешно. Запросы, отклоненные по ограничению частоты, и ответы с ошибкой, включая 408, в расход не входят – повтор такого запроса лицензию не тратит. Исключение – ответы 502 и 504: обращение могло дойти до нейросети, завершиться у нее успешно и попасть в расход, хотя клиент получил ошибку.
Когда квота токена исчерпана, токен блокируется автоматически, и все последующие запросы получают ответ 403. Снять такую блокировку может администратор инсталляции, увеличив квоту. Читайте подробнее в статье API-токены.