Status page и fallback: устойчивый клиент AI API

Определите, что означает «здоровый» сервис

Health check должен быть маленьким, безопасным и полезным: проверить DNS и TLS на уровне платформы, выполнить авторизованный server-side запрос к разрешённому read-only endpoint либо проверить собственную очередь и свежесть каталога. Не посылайте в health check пользовательские prompts, дорогие видео-задачи или ключ в браузер. Результат лучше свести к нескольким состояниям: healthy, degraded, unavailable и unknown.

Состояние unknown важно: монитор не получил достаточно данных, а не доказал аварию. Храните время последней успешной проверки, код ответа и короткую причину. Пользовательская status page должна объяснять влияние на операции, время следующей проверки и ссылку на поддержку, но не раскрывать IP, внутренние идентификаторы, ключи, подробности поставщика или чужие данные. Такой подход помогает честно сообщать о риске без неподтверждённых обещаний.

Отделите ошибку клиента от деградации

HTTP 400 и 422 обычно требуют исправить payload, а не переключать модель. 401 и 403 требуют проверить собственный ключ RussiaAPI, права и окружение; ключ нельзя отправлять в поддержку. 429 означает, что приложению нужно уменьшить параллельность, поставить работу в очередь или дождаться управляемого интервала. 5xx, timeout и сетевые ошибки могут быть временными, но всё равно нуждаются в дедлайне и ограниченном числе повторов.

В журнале храните безопасный request ID, класс ошибки, время и внутренний маршрут, а не Authorization, prompt или персональные данные. Клиенту возвращайте стабильный прикладной код: например, temporarily_unavailable или request_needs_correction. Это позволяет UI предложить повтор позже либо исправление ввода, не называя внешнюю систему виновником и не создавая непредсказуемые автоповторы. Диагностика 429 описана в отдельном руководстве.

Fallback — это явная политика продукта

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

При переключении сообщайте пользователю, если это меняет результат или стоимость его операции. Для операций с побочным эффектом — отправки письма, записи в базу, создания оплачиваемого видео — сначала проверьте idempotency key и статус исходной попытки. Fallback не должен повторно выполнить действие. Актуальный каталог и права проекта остаются источником технической истины; схема выбора моделей приведена в материале о выборе модели.

Пример: ограниченный маршрут с fallback

Ниже пример Node.js 18+ для read-only текстовой операции. Он использует только собственный ключ из окружения, короткий deadline и заранее заданный список конфигураций. Названия моделей намеренно приходят из вашей server-side конфигурации: перед выпуском подтвердите их текущим каталогом. Этот фрагмент не должен применяться для задач с побочным эффектом без идемпотентности и отдельной бизнес-проверки.

const routes = [process.env.RUSSIAAPI_PRIMARY_MODEL, process.env.RUSSIAAPI_FALLBACK_MODEL].filter(Boolean);
for (const model of routes) {
  const res = 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({ model, messages: input.messages }), signal: AbortSignal.timeout(10_000)
  });
  if (res.ok) return await res.json();
  if (![408, 429, 500, 502, 503, 504].includes(res.status)) throw new Error(`non_retryable_${res.status}`);
}
throw new Error('temporarily_unavailable'); // log status class, never the key or prompt

Если оба маршрута не прошли, сохраните только безопасный контекст расследования и отдайте контролируемое сообщение. Не подставляйте другой ключ, не увеличивайте timeout бесконечно и не отправляйте исходный prompt в сторонние сервисы диагностики. Для отмены и deadline используйте правила из руководства по timeout и retry.

Сделайте status page полезной, но не вводящей в заблуждение

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

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

Тестируйте именно границы

В автоматических тестах смоделируйте timeout, 429, 5xx, невалидный JSON, пустой каталог, отсутствие основного model ID и отказ обоих разрешённых маршрутов. Проверьте, что текстовый fallback выполняется один раз, сообщение пользователю понятно, а метрики получают событие без секрета. Для задач записи подтвердите, что никакого fallback не происходит без специального безопасного алгоритма.

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

Чек-лист перед выпуском

1. Health check малый, server-side и не содержит пользовательских данных.
2. Коды ошибок разделены на исправление ввода, права, квоту и временную деградацию.
3. Fallback разрешён только для протестированных задач и конфигураций.
4. Есть дедлайн, ограниченные повторы, idempotency для опасных операций и kill switch.
5. Status page показывает наблюдаемое состояние, а логи не содержат ключей и prompts.

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