Практическое руководство для разработчиков

Ошибки 400 и 422 в AI API: JSON, schema и диагностика

Ошибка 400 или 422 в AI API обычно означает, что сервер не может принять тело запроса в его текущей форме: JSON сломан, поле имеет неверный тип, обязательное значение отсутствует или схема не проходит проверку. Надёжная диагностика начинается с минимального обезличенного запроса и request ID, а не с пересылки ключа или полного лога в поддержку.

Чем 400 отличается от 422

Обе ошибки относятся к входу, но их точный смысл задаёт конкретный сервис и endpoint. Часто 400 указывает на некорректный синтаксис, заголовок или несовместимую комбинацию полей, а 422 — на корректный JSON, который не проходит семантическую проверку. Не полагайтесь только на название статуса: сохраните безопасный код, время и message без секретов, затем сверяйте контракт текущего endpoint.

Сначала подтвердите базовые условия: URL не содержит лишнего пути, Content-Type равен application/json, модель взята из текущего каталога, а тело сериализуется один раз. Ошибка в JSON не исправляется сменой ключа, а ошибка доступа не становится 400/422 от повторов. Такое разделение экономит время и не создаёт ненужных рисков.

Постройте минимальный воспроизводимый запрос

Уберите инструменты, streaming, пользовательские поля и большой контекст. Оставьте модель, одно сообщение и небольшое ограничение ответа. Ниже пример, который локально проверяет обязательные поля, отправляет JSON и не печатает значение ключа. Он предназначен для Node.js на сервере или в CI; перед запуском задайте собственные переменные окружения.

const payload = {
  model: process.env.RUSSIAAPI_MODEL,
  messages: [{ role: 'user', content: 'Короткий тестовый текст' }],
  max_tokens: 32
};
if (!payload.model || !Array.isArray(payload.messages)) throw new Error('invalid local payload');
const response = await fetch('https://russiaapi.com/v1/chat/completions', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.RUSSIAAPI_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify(payload)
});
if ([400, 422].includes(response.status)) console.error('validate payload by request ID');

Сначала зафиксируйте проверяемый контракт

Интеграция начинается не с копирования длинного примера, а с короткого контракта: какой endpoint используется, кто хранит секрет, какую модель разрешено выбрать, какой ответ считается успешным и как выглядит безопасная ошибка. Проверьте текущий каталог для своего проекта через /v1/models. Каталог, права и идентификаторы моделей могут меняться, поэтому статический список из статьи нельзя считать обещанием доступности.

Ключ хранится только на сервере, в защищённом credential-хранилище или в CI secret. Не помещайте его в браузерный JavaScript, экспорт коллекции, workflow-файл, скриншот, URL или обычный лог. Для первого теста берите синтетический текст без персональных данных. В журнале достаточно времени, статуса, задержки и request ID; заголовок Authorization, prompt и полный ответ исключаются или маскируются.

Как пройти тест без ложной уверенности

Один ответ 200 подтверждает лишь один путь в одном окружении. Перед выпуском отдельно проверьте недоступную модель, ошибочный JSON, отказ в доступе, ограничение частоты и тайм-аут. Не создавайте нагрузку только ради проверки 429: обработчик можно проверить на mock-ответе. Для записи или асинхронной операции не выполняйте бесконечный retry — сначала сохраните идентификатор операции и выясните её состояние.

Затем добавьте небольшой rollout: отдельная тестовая среда, ограниченный бюджет, понятный владелец и критерий остановки. Сравнивайте одинаковые входы и одну версию конфигурации. Если результат отличается, не меняйте одновременно endpoint, модель и SDK: иначе причина станет неясной. Практики deadline, отмены и безопасных повторов разобраны в руководстве по тайм-аутам.

Что именно измерять

Полезная метрика — не число отправленных запросов, а доля завершённых пользовательских задач. Для неё фиксируют код ответа, класс ошибки, задержку, число ограниченных повторов и стоимость успешной операции, если она доступна в текущем кабинете. Разделяйте ошибку входа, ошибку доступа, ошибку в теле запроса, временный сбой и лимит: у этих случаев разные действия оператора.

При инциденте не просите пользователя прислать секрет в чат. Достаточно обезличенного времени, статуса, endpoint без query-параметров, ID запроса и минимального воспроизводимого тела без чувствительных полей. Такой набор позволяет диагностировать проблему и не превращает поддержку в канал утечки. Подробнее о маскировании событий — в статье о безопасных логах AI API.

Если такой запрос проходит, возвращайте дополнительные поля по одному и сохраняйте версию конфигурации. Если он не проходит, не добавляйте случайные параметры и не заменяйте endpoint. Проверьте ID модели через /v1/models, затем сравните схему входа с документацией RussiaAPI и вашим адаптером.

Частые ошибки в теле

На практике проблемой становятся строка вместо массива сообщений, объект вместо строки в content, числовое поле в кавычках, пустой model, лишняя запятая при ручной сборке JSON или двойная сериализация. Ещё одна причина — смешение форматов разных SDK: похожее имя поля не доказывает одинаковую семантику. Собирайте payload типизированным объектом и валидируйте его до сетевого вызова.

Для structured output не считайте JSON Schema универсально поддержанной. Сначала подтвердите возможность для выбранной модели и добавьте fallback, который сообщает о неподдерживаемом режиме, а не выдаёт неверный JSON за успешный результат. Сервер обязан повторно валидировать данные перед записью в БД, вызовом инструмента или отправкой пользователю.

Логи и поддержка без утечки

Запишите request ID, HTTP-статус, время, endpoint без query, версию кода и перечень имён полей. Не записывайте Authorization, API key, cookie, полный prompt, персональные данные или полный ответ модели. При необходимости создайте обезличенный fixture с тем же типом и длиной поля. Такая запись позволяет различить ошибку формы и ошибку окружения, не создавая новый инцидент безопасности.

Если 400/422 появился после обновления SDK, зафиксируйте старую и новую версии, один и тот же fixture и различие сериализованного тела. Не переключайте весь трафик до контрактного сравнения. Стратегию адаптера и постепенного rollout можно использовать из материала о миграции OpenAI SDK.

Когда ошибка не в JSON

401 и 403 требуют проверки среды, собственного ключа и прав проекта; у них другой порядок диагностики. 429 означает ограничение нагрузки и требует очереди либо ограниченного backoff. Тайм-аут означает, что результат операции может быть неизвестен, поэтому опасно автоматически создать дубликат. Не объединяйте эти ветки в один catch с текстом «повторить».

Если API возвращает понятное поле ошибки, покажите пользователю действие, которое не раскрывает внутреннюю реализацию: «проверьте обязательные поля» или «обновите форму». Внутренний журнал получает request ID и классификацию. Для функции с инструментами добавьте серверную allowlist-проверку: модельный ответ не является разрешением выполнять произвольную команду.

Чек-лист исправления

Сведите проблему к одному обезличенному запросу, проверьте JSON локально, сверяйте типы и обязательные поля, подтвердите модель текущим каталогом, снимите безопасный request ID и добавляйте поля по одному. После исправления напишите тест на именно найденный дефект. Это предотвращает возврат ошибки при следующей смене SDK, модели или формы интерфейса.

FAQ

Читайте также

• JSON Schema и validation
• Проверка аргументов function calling
• Логи без утечек
• Документы RussiaAPI