Ошибки REST API

Обновлено 27 августа 2025

На этой странице вы найдете краткое описание ошибок REST API GigaChat, примеры ошибок, причины их возникновения, а также возможные способы решения.

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

Возможные причины возникновения ошибки при получении токена доступа:

Проблема

Решение

Не задан заголовок RqUID или форма заголовка не соответствует uuid4.

Добавьте в запрос заголовок RqUID с произвольным идентификатором запроса в формате uuid4.

---

В поле scope не указана версия API, к которой выполняется запрос:

  {
    "code": 5,
    "message": "scope is empty"
  }

Укажите версию API, к которой выполняется запрос:

GIGACHAT_API_PERS — доступ для физических лиц.

GIGACHAT_API_B2B — доступ для ИП и юридических лиц по предоплате.

GIGACHAT_API_CORP — доступ для ИП и юридических лиц по постоплате.

---

Ключ авторизации не соответствует версии API, которая указана в поле scope или не указана версия API:

  {
    "code": 7,
    "message": "scope from db not fully includes consumed scope"
  }

Укажите корректную версию API. Версия API отображается в личном кабинете.

GigaChain по умолчанию работает с версией API для физических лиц — GIGACHAT_API_PERS.

Для использования другой версии API явно укажите ее в параметре scope при инициализации объекта GigaChat:

  llm = GigaChat(
    credentials="ключ_авторизации",
    scope="GIGACHAT_API_B2B",
    model="GigaChat-Pro",
  )

---

Поле scope содержит невалидные данные:

  {
    "code": 1,
    "message": "scope data format invalid"
  }

Возможно, версия API указана с ошибкой. Проверьте значение поля scope и попробуйте еще раз.

Если ошибка возникает при отправке других POST-запросов, то тело ошибки будет содержать название параметра, который привел к ошибке:

{
    "status": 400,
    "message": "Id must not be empty"
}

Ошибка авторизации

Ошибка может возникать при запросе токена доступа.

Проблемы, которые вызывают ошибку:

Проблема

Решение

Заголовок Authorization содержит некорректные данные:

  {
    "code": 4,
    "message": "Can't decode 'Authorization' header"
  }

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

---

Ключ авторизации, который передается в заголовке Authorization не соответствует версии API, заданной в поле scope:

  {
    "code": 6,
    "message": "credentials doesn't match db data"
  }

Перевыпустите ключ авторизации в личном кабинете и попробуйте снова.

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

Пример:

{
    "status": 401,
    "message": "Unauthorized"
}

Для исправления ошибки укажите корректный токен доступа.

Требуется оплатить сервис

Проблема

Решение

Закончились токены модели, к которой выполняется запрос.

{
    "status": 402,
    "message": "Payment Required"
}

Проверьте лимит токенов модели в личном кабинете и убедитесь, что вы передаете запросы именно в ту модель, у которой закончились токены.

После этого пополните баланс в личном кабинете.

Нет доступа к запрашиваемому ресурсу

Проблема

Решение

Ошибка возникает при отправке запроса GET /balance, если вы оплачиваете работу с API по схеме pay-as-you-go.

Это связано с тем, что метод возвращает остаток предоплаченных токенов, которых не может быть при оплате API по факту использования.

Пример:

{
    "status": 403,
    "message": "Permission denied"
}

Превышен максимальный размер входных данных

Проблема

Решение

Превышен максимальный размер входных данных.

Пример:

{
    "status": 413,
    "message": "Payload too large"
}

Для решения проблемы уменьшите размер промпта. Количество токенов в промпте должно быть меньше размера окна контекста модели. Оценить количество токенов в промпте можно с помощью запроса POST /tokens/count.

Ошибка валидации параметров запроса

Проблема

Решение

Модель не поддерживает пользовательские функции. Ошибка может возникнуть при вызове пользовательских функций.

{
    "status": 422,
    "message": "Requested model does not support functions"
}

Для решения проблемы — обратитесь на почту.

---

Некорректный порядок сообщений.

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

{
    "status": 422,
    "message": "Invalid params: system message must be the first message"
}

Перед отправкой запроса проверьте порядок сообщений, названия полей и значения параметров.

---

Содержимое текстового файла, переданного в поле attachments, превышает размер контекста модели.

{
    "status": 422,
    "message": "Unprocessable Entity for url: <...>/chat/completions"
}

Разделите или сократите текст в файле.

Слишком много запросов

Проблема

Решение

Выполнено слишком много запросов.

Пример:

{
    "status": 429,
    "message": "Too Many Requests"
}

Количество выполняемых одновременных запросов не соответствует вашему client_id. По умолчанию физическим лицам доступен один одновременный поток, а ИП и юридическим лицам — 10.

Внутренняя ошибка сервиса

Проблема

Решение

Произошла ошибка сервиса.

Пример:

{
    "status": 500,
    "message": "Internal Server Error"
}

Обратитесь в службу поддержки.

Контакты

Если проблема сохраняется, обратитесь в поддержку по электронной почте.