RussiaAPI

Надёжность API

Тайм-аут AI API: отмена, retry и статусы операций

Тайм-аут не говорит, что запрос обязательно провалился. Он говорит лишь, что ваш компонент перестал ждать надёжный ответ в выбранный срок. Для AI API это критично: операция могла ещё выполняться, пользователь мог закрыть вкладку, а повтор того же действия иногда создаёт второй счёт, второй ответ или вторую видео-задачу. Надёжная интеграция строит deadline, статус и правила повтора вместе.

Опубликовано 18 августа 2026 · 12 минут чтения · Ключевой запрос: тайм-аут AI API отмена retry

Контекст сервиса. RussiaAPI — независимый сторонний API gateway, не официальный сервис производителей моделей. Каталог, лимиты и поддерживаемые способы отмены меняются; сверяйте актуальную документацию. Эта статья не предлагает обходить ограничения, не обещает доступность конкретной модели и не просит ключи других поставщиков. Используйте только собственный ключ RussiaAPI в защищённой серверной среде.

Нарисуйте жизненный цикл, а не один запрос

Пользователь нажимает кнопку, браузер отправляет запрос вашему серверу, сервер валидирует вход и обращается к API. Далее есть несколько исходов: быстрый успех, понятная ошибка конфигурации, временный лимит, обрыв соединения или работа, которая продолжается дольше HTTP-окна. Если система хранит только «успех/ошибка», после тайм-аута она теряет важное состояние. Минимальная модель обычно включает created, running, succeeded, failed, cancelled и unknown.

unknown — не признак плохого продукта, а честный результат при разрыве связи, когда подтверждение не получено. Не заменяйте его сразу новой операцией. Сначала запросите статус, если endpoint документирует task ID или другой безопасный идентификатор, либо покажите пользователю «проверяем результат». Для асинхронных видео-сценариев это особенно важно: создание задачи, polling и webhook — разные стадии. Их схема описана в руководстве по асинхронной генерации видео.

Выберите один общий deadline

У запроса есть таймеры браузера, CDN или reverse proxy, вашего приложения, SDK и внешнего API. Если они настроены случайно, пользователь получает обрыв раньше, чем сервер закончит работу, а сервер продолжает держать ресурсы. Определите продуктовый deadline для конкретной операции и сделайте внутренние тайм-ауты немного короче внешних. Например, сервер может дать внешнему вызову 18 секунд при пользовательском SLA в 20 секунд, чтобы успеть сформировать контролируемый ответ и записать статус.

Не переносите одно значение на всё. Короткая классификация, streaming-чат и генерация видео имеют разные UX и разные способы возврата результата. Длительная операция обычно должна быстро вернуть ID и работать через очередь или callback, а не удерживать синхронное соединение десять минут. Ограничьте размер входа и ожидаемый размер результата: огромный prompt или неограниченная генерация часто выглядят как «медленный поставщик», хотя проблема находится в контракте приложения.

Пример отмены в Node.js

Ниже минимальный серверный пример с AbortController. Он подходит как каркас для запроса без побочного эффекта; перед автоматическим повтором длительной задачи добавьте собственный operation ID и проверку статуса. Не передавайте ключ в браузер и не копируйте в production обработчик без аутентификации, валидации входа, ограничения размера и журналирования с маскированием секретов.

export async function callModel(body) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 18_000);
  try {
    const response = await fetch('https://russiaapi.com/v1/chat/completions', {
      method: 'POST', signal: controller.signal,
      headers: { Authorization: `Bearer ${process.env.RUSSIAAPI_API_KEY}`,
        'Content-Type': 'application/json' },
      body: JSON.stringify(body)
    });
    if (!response.ok) throw new Error(`upstream_${response.status}`);
    return await response.json();
  } finally {
    clearTimeout(timer);
  }
}

Отмена прекращает ожидание этого fetch в вашем процессе, но не доказывает, что внешний сервис не получил запрос. Поэтому обработчик ошибки должен различать AbortError, 429, 4xx и 5xx. Клиенту не нужна полная техническая причина: верните стабильный код приложения, request ID и следующий безопасный шаг. Внутри запишите время, класс ошибки и operation ID, но никогда не печатайте Authorization, API Key, cookie или целый пользовательский текст.

Когда retry допустим

Повтор — это решение о семантике, а не о сетевой библиотеке. Допустимый кандидат: запрос на получение списка моделей или детерминированное чтение, если его не ограничивает политика. Рискованный кандидат: создание задачи, отправка результата в сторонний сервис, запуск video generation или function calling. Для последнего повторайте не «на всякий случай», а только после проверки, что предыдущее действие не выполнено, либо используйте идемпотентный ключ, который ваш сервис связывает с бизнес-операцией.

Даже для допустимого retry поставьте потолок попыток, общий бюджет времени и случайный jitter. Одновременный повтор тысяч запросов после краткого сбоя создаёт повторный пик. Код 429 требует в первую очередь уменьшить конкурентность или поместить работу в очередь; менять ключ, регион или endpoint ради обхода ограничения нельзя. Практические формулы backoff и пределы рассмотрены в статье об ошибке 429.

Отмена пользователем и результат

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

Для callback проверяйте подпись по правилам конкретной документации, записывайте event ID и отвечайте быстро. Повторная доставка webhook — нормальна, поэтому обработчик должен быть идемпотентным. Нельзя считать любой входящий JSON достоверным или подставлять URL callback из пользовательского поля. В материале о webhook для video API разобраны проверка подписи, дедупликация и безопасная обработка.

Что наблюдать после релиза

Метрика «средняя задержка» скрывает худшие сценарии. Смотрите p50/p95/p99, долю тайм-аутов, долю unknown, число отмен пользователем, повторов и дублей, а также время до окончательного статуса. Разделяйте данные по операции и версии конфигурации, но не по секретам или сырым prompts. Если после изменения выросли 429 или тайм-ауты, сначала снизьте параллелизм и проверьте размер задач, затем включите rollback через feature flag.

Перед выпуском проведите тест с медленным соединением, закрытием вкладки, некорректной моделью, 429, пустым ответом и повтором одного operation ID. Используйте синтетические данные. Такая проверка даёт больше уверенности, чем один удачный demo-prompt, и помогает не выдавать «ошибка» там, где система ещё должна уточнить состояние.

Постройте контролируемый первый сценарий

В консоли RussiaAPI создайте собственный тестовый ключ, проверьте актуальный каталог и добавьте deadline с журналированием безопасных статусов. Подключайте production-трафик постепенно, наблюдая тайм-ауты и стоимость завершённой задачи.

Открыть консоль RussiaAPI

FAQ

Нужно ли повторять запрос после тайм-аута?

Не автоматически. Сначала установите, мог ли запрос уже создать побочный эффект. Для чтения возможен ограниченный retry, а для длительной задачи или внешнего действия нужно проверить operation ID и конечный статус.

Чем тайм-аут отличается от ошибки 429?

Тайм-аут завершает ваше ожидание раньше подтверждения. 429 сообщает об ограничении частоты или квоты. Для 429 уменьшают параллелизм и используют backoff; при тайм-ауте проверяют deadline, сеть, размер работы и статус.

Можно ли отменить уже принятую видео-задачу?

Это зависит от документированного endpoint-а. Закрытие HTTP-соединения не гарантирует отмену внешней работы, поэтому после отмены клиента сохраняйте честный статус и проверяйте фактическое состояние задачи.

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