GuidesOneMux

Сбои OpenAI API в production: диагностика, повторные запросы и безопасное восстановление

Практическая схема для диагностики ошибок аутентификации, лимитов запросов, тайм-аутов, сбоев сервера и некорректных ответов OpenAI API — и выбора между повторной попыткой, исправлением и восстановлением.

AI

Кратко · TL;DR

Обработка ошибок в production начинается с классификации сбоя, а не с повторной отправки каждого запроса. В этом руководстве ошибки конфигурации и квот отделены от временных ограничений частоты запросов, тайм-аутов, сбоев сервера и некорректных ответов; также приведены ограниченный шаблон повторных запросов на JavaScript и список проверок для восстановления.

Главное

  • Не повторяйте запросы при ошибках аутентификации, разрешений, некорректных запросах или исчерпанных кредитах, пока не устранена причина.
  • При ограничениях частоты запросов и перегрузке учитывайте `Retry-After`, если он указан, и ограничивайте число попыток экспоненциальной задержкой и случайным разбросом.
  • Тайм-аут не доказывает, что операция не завершилась; не повторяйте бездумно неидемпотентные действия.
  • Проверяйте успешные ответы до фиксации состояния последующих этапов процесса и сохраняйте достаточно контекста для безопасного восстановления.
В этой статье (6)

Правило для production: сначала классифицируйте сбой, затем повторяйте запрос

При сбое вызова OpenAI API важно спрашивать не просто: «Стоит ли повторить запрос?», а: «Какие данные указывают на временный характер сбоя и к чему приведёт дублирование запроса?» В production-процессе нужно классифицировать ошибку, выполнить ограниченное действие и сохранить состояние задачи, если безопасно продолжить нельзя.

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

Первичная диагностика по типу сбоя

СимптомВероятное действиеПовторять запрос?
Ошибка аутентификации 401Проверьте, что ключ API верен и активен, а также что используется нужная организация. Если настроен список разрешённых IP-адресов, проверьте его.Нет, пока не исправлены учётные данные или доступ.
Неверный запрос 400Проверьте сообщение и параметры запроса, включая обязательные входные данные, кодировку, формат и размер.Нет, пока запрос не исправлен.
429: ограничение частоты запросов или сообщение «slow down»Снизьте параллелизм или частоту запросов. Если указан Retry-After, соблюдайте его, а затем постепенно увеличивайте нагрузку.Да, в рамках ограниченной политики повторов.
429: кредиты, расходы или лимит использованияПроверьте error.code; пополните кредиты или устраните соответствующее ограничение.Нет. Повтор того же запроса не восстановит доступ.
Ошибка сервера 500 или перегрузка 503Ненадолго подождите, соблюдайте Retry-After, если он указан, и повторите запрос в пределах установленного лимита.Обычно да, с необходимыми мерами предосторожности.
Тайм-аут на стороне клиента или ошибка соединенияПроверьте сеть, прокси, TLS и настройки межсетевого экрана; выясните, мог ли запрос завершиться.Иногда; сначала учтите возможные последствия дублирования.
Успешный статус, но непригодный ответПеред переходом процесса к следующему этапу проверьте структуру ответа и наличие обязательных полей.Не автоматически. Обрабатывайте такой случай отдельно как проблему качества данных или протокола.

В руководстве OpenAI указано, что RateLimitError в Python соответствует 429, а InternalServerError — 503; поэтому перегрузка может возвращаться с кодом, отличным от того, который раньше ожидал обработчик. В любом клиенте учитывайте и статус, и подробности ошибки, а не предполагайте, что всякая перегрузка обозначается кодом 429.

Ограниченный шаблон повторных запросов на JavaScript

Предварительные условия: актуальная версия JavaScript SDK OpenAI, настроенный ключ API и процесс, в котором можно безопасно определить, допустим ли повтор запроса. Этот иллюстративный пример повторяет запрос только при некоторых временных сбоях. Он не доказывает, что запрос, завершившийся тайм-аутом, не был обработан.

import OpenAI from "openai";

const client = new OpenAI();

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

function retryAfterMs(error) {
  const value = error.headers?.get?.("retry-after");
  if (!value) return null;

  const seconds = Number(value);
  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);

  const dateMs = Date.parse(value);
  return Number.isNaN(dateMs) ? null : Math.max(0, dateMs - Date.now());
}

function isRetryable(error) {
  const code = error.code;
  if ([
    "credit_balance_exhausted",
    "organization_spend_limit_exceeded",
    "project_spend_limit_exceeded",
    "organization_usage_limit_exceeded",
  ].includes(code)) return false;

  return error instanceof OpenAI.RateLimitError ||
    (error instanceof OpenAI.APIError &&
      [500, 503].includes(error.status));
}

async function createResponseWithRetry(input, maxRetries = 3) {
  for (let attempt = 0; ; attempt++) {
    try {
      return await client.responses.create({
        model: "YOUR_MODEL",
        input,
      });
    } catch (error) {
      if (!isRetryable(error) || attempt >= maxRetries) throw error;

      const exponentialMs = Math.min(10_000, 500 * 2 ** attempt);
      const jitterMs = Math.floor(Math.random() * 250);
      const delayMs = retryAfterMs(error) ?? exponentialMs + jitterMs;
      await sleep(delayMs);
    }
  }
}

YOUR_MODEL — это заполнитель, а не рекомендация по выбору модели. Пример показывает управление повторами, а не подтверждённое поведение для всех версий SDK и конечных точек. Убедитесь, что установленная версия SDK предоставляет заголовки ответа способом, показанным в примере; если нет, используйте поддерживаемый механизм для их чтения. Помимо числа попыток задайте общий дедлайн процесса, чтобы зависшая задача не ожидала бесконечно.

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

Для тайм-аутов и некорректных ответов нужны правила восстановления

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

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

Операционный контрольный список

  1. Записывайте время и часовой пояс, конечную точку, модель, HTTP-статус, тип и код ошибки, а также безопасный идентификатор для сопоставления запросов.
  2. Никогда не записывайте в журналы ключи API или конфиденциальные входные данные. Сохраняйте только те сведения о запросе, которые необходимы для безопасного воспроизведения сбоя.
  3. Повторяйте запросы только при временных сбоях, задавая максимальное число попыток, задержку, случайный разброс и общий дедлайн.
  4. Если указан Retry-After, соблюдайте его; при продолжающемся ограничении частоты запросов дополнительно снизьте нагрузку.
  5. Отделяйте исчерпание повторов от постоянной ошибки, чтобы операторы могли проверить подходящие задачи и запустить их повторно.
  6. При постоянных ошибках соберите модель, сообщение и код ошибки, данные запроса и заголовки с удалёнными секретами, время и часовой пояс, а также другой релевантный контекст. OpenAI рекомендует передавать эти сведения в службу поддержки.

Заключение

Надёжные процессы с OpenAI API отличают временную нагрузку на сервис от ошибок, требующих изменения конфигурации или лимитов. Осторожно повторяйте запросы при ограничении частоты и сбоях сервиса; исправляйте ошибки аутентификации и запросов; обрабатывайте тайм-ауты и некорректные ответы как отдельные состояния восстановления. Такая классификация не даст циклу повторных попыток превратить единичный сбой вызова в более серьёзный инцидент в production.

Вопросы

Нужно ли повторять каждый запрос OpenAI API с ответом 429?

Нет. Повторяйте запросы при ограничении частоты с паузами, ограниченным числом попыток и соблюдением `Retry-After`, если он указан. Если причина 429 — исчерпанные кредиты или лимит расходов либо использования, нужно устранить это ограничение: повтор вызова не восстановит доступ. Проверьте код ошибки.

Как процессу обрабатывать тайм-аут OpenAI API?

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

Что делать, если API вернул некорректный ответ?

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

Означает ли 503 то же самое, что 429?

Нет. В предоставленных рекомендациях OpenAI ответы 429 при ограничении частоты запросов и ответы 503 при перегрузке модели описаны как разные случаи. Клиенту следует проверять статус и подробности ошибки и при необходимости обрабатывать оба случая, а не предполагать, что перегрузка всегда обозначается кодом 429.

Похожие статьи

Guides

Qwen3.8-Max задаёт новую планку – GPT-5.6 Sol — ваш практичный ИИ для кода на OneMux

Qwen3.8-Max устанавливает новый бенчмарк для ИИ-кодинга, но GPT-5.6 Sol — это модель, которую вы можете использовать уже сегодня через OpenAI-совместимый API OneMux. Сравните цены и начните работу.

阅读全文 →

Guides

Обзор GPT-5.6 Sol: кому действительно нужен флагман OpenAI по сравнению с DeepSeek и Qwen

Практический обзор GPT-5.6 Sol: сравнение флагмана OpenAI с DeepSeek V4 и Qwen, включая цены, интеграцию с OpenAI API и рекомендации по выбору.

阅读全文 →

Guides

Управление затратами на API ИИ с GPT-5.6 Sol: Практическое руководство для разработчиков

Узнайте, как эффективно управлять затратами на OpenAI API с помощью GPT-5.6 Sol через OneMux. Изучите разбивку цен, стратегии экономии и сравнение моделей.

阅读全文 →

Guides

Почему Claude Opus 4.7 — лучшая модель ИИ для программирования прямо сейчас

Сравнение Claude Opus 4.7 и GPT-5.4 для программирования: качество кода, логика и стоимость. Узнайте, как OneMux предоставляет единый доступ к обеим моделям через API, совместимый с OpenAI.

阅读全文 →