Ошибки

Обработка ошибок

Наше API использует стандартные коды ответов HTTP для индикации успеха или неудачи запроса. В случае ошибки тело ответа будет содержать JSON-объект с дополнительной информацией, помогающей диагностировать проблему.

Структура ответа при ошибке

Все ошибки, возвращаемые API, имеют единую структуру для удобства программной обработки.

{
  "error": {
    "message": "Подробное описание того, что пошло не так.",
    "type": "тип_ошибки",
    "code": 4xx_или_5xx_код
  }
}

message (string): Человекочитаемое описание ошибки.
type (string): Уникальный идентификатор типа ошибки (например, unauthorized_request, rate_limit).
code (integer): HTTP-код состояния, соответствующий ошибке.

Коды ошибок

Ниже приведено подробное описание основных ошибок, с которыми вы можете столкнуться.

400 Bad Request

Тип: bad_request

Эта ошибка указывает на то, что сервер не смог обработать ваш запрос из-за фундаментальной проблемы в нём, не связанной с валидацией полей (см. ошибку 422).

Возможные причины:

Запрос не соответствует требованиям безопасности или цензуры.
Запрос содержит неподдерживаемые или недоступные данные.
Общая некорректность запроса, которую сервер не может обработать.

401 Unauthorized

Тип: unauthorized_request

Возникает, если ваш запрос не был авторизован.

Возможные причины:

API ключ не предоставлен в заголовке Authorization.
Предоставленный API ключ недействителен или указан с ошибкой.

402 Payment Required

Тип: zero_balance

Эта ошибка означает, что на балансе вашего API ключа недостаточно средств для выполнения запроса.

Возможные причины:

Ваш баланс равен нулю.

403 Forbidden

Тип: access_forbidden

Доступ к API временно или постоянно запрещён. Эта мера предназначена для защиты сервиса от злоупотреблений и непреднамеренных DDoS-атак.

Возможные причины:

Слишком большое количество запросов с неверным API ключом (ошибка 401) за короткий промежуток времени.
Слишком большое количество запросов к API при нулевом балансе (ошибка 402).
Слишком частое превышение лимитов на запросы (ошибка 429).
Попытка подбора API ключа или кода пополнения может привести к постоянной блокировке без возможности разблокировки.

404 Not Found

Тип: not_found

Указывает, что запрашиваемый ресурс не найден.

Возможные причины:

ID модели, указанный в запросе, не существует или модель отключена.
Вы пытаетесь использовать модель с конечной точкой (эндпоинтом), которая её не поддерживает (например, модель для генерации текста в эндпоинте для генерации изображений).
Неверный URL-адрес конечной точки API.

408 Request Timeout

Тип: request_timeout

Возникает, если обработка вашего запроса моделью заняла слишком много времени и была прервана, чтобы избежать "зависания".

Возможные причины:

Высокая нагрузка на модель.
Внутренний сбой модели при обработке сложного запроса.

413 Payload Too Large

Тип: payload_too_large

Эта ошибка означает, что ваш запрос слишком велик для обработки.

Возможные причины:

Количество токенов в вашем запросе (например, в поле messages для чат-моделей) превышает максимальную длину контекста для выбранной модели.

422 Unprocessable Entity

Тип: invalid_request_error

Указывает на то, что запрос синтаксически корректен, но содержит неверные или невалидные значения в полях, которые не соответствуют документации.

Возможные причины:

Неверное значение для перечисляемого поля (например, role: "userok" вместо role: "user").
Неподдерживаемый размер изображения, неверный формат данных и т.д.
В поле message ответа на эту ошибку обычно содержится подробная информация о том, какое именно поле и почему является невалидным.

429 Too Many Requests

Тип: rate_limit

Возникает, когда вы превысили свой лимит на количество запросов в минуту (RPM).

Возможные причины:

Слишком высокая частота отправки запросов. Проверьте ваш текущий лимит RPM.

500 Internal Server Error

Тип: internal_server_error

Общая ошибка, указывающая на непредвиденный сбой на стороне нашего сервера. Если вы столкнулись с этой ошибкой, пожалуйста, повторите запрос позже.

503 Service Unavailable

Тип: service_unavailable

Эта ошибка означает, что запрашиваемая вами модель или сервер провайдера в данный момент полностью недоступны для обработки запросов. В отличие от других ошибок, связанных с таймаутами, ошибка 503 указывает на фундаментальную проблему доступности сервиса, а не на временные задержки в обработке конкретного запроса.

Возможные причины:

Перегрузка модели: Серверы модели получили количество запросов, превышающее их текущую пропускную способность. В результате система не может принять новые запросы до тех пор, пока не освободятся ресурсы.
Технические проблемы на стороне провайдера: Могут возникать сбои в работе серверного оборудования, проблемы с программным обеспечением, обслуживающим модель, или плановые технические работы, о которых пользователи не были заранее предупреждены.
Отключение модели для обслуживания: Провайдер мог временно отключить модель для обновления, настройки или решения обнаруженных проблем.
Проблемы с инфраструктурой: Сбои в системах охлаждения, электропитания или сетевой инфраструктуре дата-центра, где размещены серверы модели.

Особенности ошибки: При возникновении ошибки 503 клиентский запрос даже не начинает обрабатываться моделью, в отличие от ошибки 408, где обработка начата, но не завершена в срок. Сервер явно сообщает о своей недоступности, что позволяет клиенту понять, что повторная попытка может быть предпринята позже.

504 Gateway Timeout

Тип: gateway_timeout

Эта ошибка означает, что сервер-шлюз не получил своевременного ответа от другого сервера (в данном случае от сервера провайдера нейросети) при попытке получить доступ к запрашиваемому ресурсу.

Возможные причины:

Сервер провайдера нейросети перегружен и не может обработать запрос в установленный срок.
Возникли технические проблемы на стороне провайдера, из-за которых ответ не был отправлен.
Сетевые проблемы между сервером-шлюзом и сервером провайдера нейросети.

Особенности ошибки: Ошибка 504 занимает промежуточное положение между ошибками 503 и 408, отражая специфику работы с серверами провайдеров нейросетей.

При ошибке 503 Service Unavailable сервер провайдера или модель полностью недоступны для обработки запросов, либо модель возвращает явную ошибку о своей недоступности. Это означает, что сервис в принципе не может в данный момент обработать запрос.

При ошибке 408 Request Timeout модель получает запрос и начинает обрабатывать его, но делает это слишком медленно. В большинстве случаев модель всё же возвращает ответ, однако это происходит за пределами допустимого времени ожидания, что приводит к прерыванию соединения со стороны клиента.

В случае с ошибкой 504 Gateway Timeout ситуация иная: соединение с сервером провайдера успешно установлено, но после этого модель не возвращает ничего - ни данных ответа, ни сообщения об ошибке. Сервер-шлюз ожидает ответ в течение установленного времени, но не получает его, что приводит к разрыву соединения по таймауту. Таким образом, ошибка 504 возникает именно в ситуации "молчания" сервера после установки соединения.