Альтернатива OpenAI API: как сравнить схему ошибок

Определите локальный контракт ошибок

Клиентскому интерфейсу не нужно знать все варианты upstream-ответа. Создайте небольшой локальный набор: input_error, access_error, throttled, temporary_failure и unknown_outcome. Для каждого состояния определите нейтральный текст пользователю, допустимость retry и необходимость ручной проверки. Это снижает связность с конкретным форматом маршрута.

Сохраняйте исходный статус только в защищённом server-side журнале и в минимально необходимом объёме. Не показывайте заголовки, тело диагностического ответа, запрос пользователя или идентификатор ключа. Технический журнал предназначен для владельца интеграции, а не для передачи в браузер или сторонний чат.

Проверьте форму, а не только код

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

Нельзя считать текст сообщения стабильным API-контрактом. Текст подходит для человека, но не для логики ветвления. Используйте документированный класс там, где он действительно доступен, и собственный parser с явным fallback «неизвестно». Такой fallback защищает от ложного успеха после изменения маршрута.

Отделите retry от исправления входа

Ошибка валидации, запрещённый параметр и несоответствие схемы не исправляются повтором. Retry может относиться только к заранее разрешённому временному состоянию и ограничиваться общим deadline, числом попыток и jitter. После лимита верните понятный статус и не создавайте новый side effect ради очередной попытки.

Особенно осторожно обрабатывайте timeout: он означает отсутствие подтверждения у клиента, а не отсутствие работы на другой стороне. Сначала сверяйте локальную операцию или безопасный статус, затем решайте, нужна ли ручная проверка. Не маскируйте неизвестный итог под успех и не отправляйте тот же запрос автоматически.

Постройте отрицательные тесты

В набор должны входить неполное тело, неизвестное поле, неверный тип, пустой идентификатор корреляции, превышенный локальный budget и ответ после отмены ожидания. Успешный тест подтверждает, что приложение не падает, не утечёт секрет и не расширит действие без явного решения. Это полезнее, чем коллекция случайных real-world ошибок.

Каждый отрицательный fixture снабдите ожидаемым действием: stop, retry_later, review или display_fix. Список обязан быть коротким и понятным для ревью. Если новая ошибка не классифицируется, выбирайте review; не придумывайте совместимость и не выпускайте mapping без синтетического подтверждения.

Обновляйте mapping вместе с адаптером

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

Продолжите с timeout, отменой и повторами, retry/backoff после 429 и idempotency key при повторе. Все три материала описывают приложение, а не обещание поддержки каждого endpoint.

Зафиксируйте границу проверки

Перед любым переключением запишите, что именно подтверждает тест: форму запроса, обработку известного ответа, локальную классификацию ошибки или безопасный rollback. Не расширяйте вывод теста за его пределы. Один успешный запрос не доказывает постоянную совместимость, стоимость, поддержку всех полей или поведение другой модели.

Тестовые данные должны быть синтетическими и обезличенными. Не помещайте в fixture пользовательский prompt, вложение, Authorization, cookie или чужой ключ. Для журнала обычно достаточно времени, версии адаптера, локального operation ID, хэша нормализованной структуры и итоговой категории. Это помогает воспроизвести решение без утечки секрета.

Проверяйте изменение на staging

Сначала запускайте сценарий на staging с ограниченным allowlist. Отделите успешный ответ от неизвестного результата, ошибки валидации, отказа прав и временной сетевой проблемы. Для каждого состояния заранее определите остановку, ручную проверку или безопасный rollback; бесконечный retry не является стратегией миграции.

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

Сделайте решение обратимым

Конфигурация должна позволять отключить новый путь без изменения пользовательских данных. Храните прежний маршрут, короткий журнал принятого решения и явные критерии остановки. Если результат неясен, маркируйте операцию для review вместо повторной отправки: timeout или неполный ответ не доказывают, что побочное действие не произошло.

Разделяйте переключение интерфейса и переключение side effect. Сначала можно показать оператору или небольшой группе диагностический результат, затем расширять охват. Такой порядок не обходит правила поставщика и не гарантирует результат; это обычная дисциплина управления риском в собственном приложении.

Минимальный набор доказательств

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

Полезно отдельно проверить, что лог не содержит секретов и что ошибка не выводится пользователю вместе с техническими деталями. Ссылка на источник объясняет общий принцип, но не заменяет контрактный тест. Никакой пример на странице не просит передавать upstream key: используйте только собственный ключ RussiaAPI на сервере.

Безопасный server-side пример

Пример ниже выполняет только локальную проверку. Он не делает сетевой вызов, не содержит реальных ключей и не доказывает поддержку endpoint. Перед подключением маршрута сверяйте актуальный контракт, каталог и условия своего аккаунта.

export function normalizeError(response) {
  const status = Number(response?.status || 0);
  if (!response || status === 0) return { kind: 'unknown_outcome', action: 'review' };
  if (status === 429) return { kind: 'throttled', action: 'retry_later' };
  if (status >= 400 && status < 500) return { kind: 'input_or_access', action: 'stop' };
  return { kind: 'temporary_or_unclassified', action: 'review' };
}

Источники и границы

RFC 9457 Problem Details · AWS Builders Library: timeouts and retries

Источники объясняют общие инженерные принципы. Они не подтверждают, что конкретная возможность включена у RussiaAPI или у вашего аккаунта. RussiaAPI не является официальным представителем упомянутых поставщиков; соблюдайте применимые правила и используйте только собственный ключ RussiaAPI на сервере.

FAQ

Нужно ли копировать таблицу кодов другого API?

Нет. Создайте локальные категории, которые нужны вашему приложению, и проверяйте документированные свойства текущего контракта. Неизвестный ответ должен попадать в review.

Можно ли retry для любой ошибки?

Нет. Повтор не подходит для ошибки формы, прав или схемы. Для временной проблемы он должен быть ограничен budget, количеством попыток и проверкой побочных действий.

Что логировать?

Минимальные технические признаки: время, версия адаптера, локальный operation ID и категория. Не логируйте ключи, заголовок Authorization, полный prompt или чужой ответ.

Следующий шаг

Откройте RussiaAPI, подтвердите доступный маршрут и протестируйте сценарий на staging. Затем продолжите с материалами: Timeout, отмена и повторы · Retry и backoff после 429 · Idempotency key при повторе.