Как понять код ошибки GigaChat API и исправить запрос без лишних повторов

Если GigaChat API вернул ошибку, сначала сохраните HTTP-код и сообщение ответа: одинаковая фраза «запрос не работает» может означать неверный параметр, истёкший токен, слишком большой файл или превышение числа одновременных обращений. Ниже — практическая памятка по официальной документации, проверенной 22 октября 2026 года. Это разбор описанных правил, а не результат собственного теста редакции.

Инструкция относится к GigaChat API для пользователей с уже созданным проектом и доступом к моделям. Страница описания ошибок обновлена 17 июля 2026 года, а справка метода генерации ответа — 7 октября 2026 года.

Что записать до исправления

1. Сохраните адрес метода, HTTP-код, поле message и время запроса. Если SDK или ответ показывает идентификатор запроса, сохраните и его: он пригодится при обращении в поддержку.
2. Не копируйте в журнал ключ авторизации, Client Secret или полный access token. Для воспроизведения достаточно отметить тип доступа и возраст токена.
3. Проверьте базовый адрес. Для новых подключений документация указывает https://api.giga.chat; прежний адрес оставлен для тех, кто подключился до 17 июля 2026 года.
4. Меняйте по одной причине за раз. Иначе будет трудно понять, какое исправление сработало.

Как читать основные коды

• 400 — ошибка в параметрах. При получении токена проверьте обязательный RqUID в формате uuid4 и значение scope. Для физлиц используется GIGACHAT_API_PERS, для бизнеса по предоплате — GIGACHAT_API_B2B, по схеме pay-as-you-go — GIGACHAT_API_CORP. В других POST-запросах сообщение обычно указывает проблемное поле.
• 401 — ошибка авторизации. Access token действует 30 минут. Получите новый токен и убедитесь, что в рабочем запросе используется заголовок Authorization со схемой Bearer. Не путайте access token с ключом авторизации, который нужен для его получения.
• 402 — закончились токены выбранной модели. Проверьте остаток и то, к какой модели обращается код. Метод GET /balance рассчитан на купленные пакеты токенов; при pay-as-you-go он сам возвращает 403, поэтому такой ответ не доказывает отсутствие рабочего баланса.
• 403 — нет доступа к ресурсу либо запрос не соответствует условиям метода. Помимо ограничения GET /balance для pay-as-you-go, документация отдельно советует передавать User-Agent, если обращение к https://api.giga.chat отвечает 403 Unauthorized.
• 413 — входные данные слишком велики. Сократите промпт или вложения. До отправки текст можно оценить методом POST /tokens/count и сравнить с окном контекста выбранной модели.
• 422 — параметры формально прочитаны, но не проходят проверку. Среди описанных причин: системное сообщение стоит не первым, системных сообщений несколько, модель не поддерживает пользовательские функции или содержимое прикреплённого текстового файла не помещается в контекст. Проверьте порядок messages и названия полей; большой документ разделите на части.
• 429 — одновременно выполняется слишком много запросов. В документации указано значение по умолчанию: один одновременный поток для физлиц и десять для ИП и юридических лиц. Сначала поставьте обращения в очередь и дождитесь завершения активного запроса; простое немедленное повторение может снова встретить тот же лимит.
• 500 — внутренняя ошибка сервиса. Сохраните безопасную диагностику без секретов и обратитесь в поддержку GigaChat API, если сбой повторяется. Не запускайте бесконечный цикл повторов: ограничьте их число и увеличивайте паузу между попытками.

Минимальный порядок проверки

1. Убедитесь, что endpoint и метод верны.
2. Для 400, 413 и 422 исправьте структуру или объём запроса.
3. Для 401 получите свежий access token; для 402 проверьте токены нужной модели; для 403 сопоставьте метод со своей схемой оплаты и заголовками.
4. Для 429 уберите параллельные вызовы и повторите позже.
5. Для повторяющегося 500 передайте поддержке код, message, время, метод и идентификатор запроса, но не секреты.

Код ошибки — только начало диагностики. Решение нужно выбирать по сочетанию статуса, message и метода: например, 403 у запроса баланса при pay-as-you-go является ограничением самого метода, а 403 Unauthorized у другого обращения требует проверки заголовков.

Основа: описание ошибок GigaChat API, авторизация и справка метода генерации ответа.