GuidesOneMux

Как безопасно диагностировать ошибки аутентификации, лимитов запросов, тайм-аутов и некорректных ответов OpenAI API

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

AI

Кратко · TL;DR

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

Главное

  • Не повторяйте запросы при ошибках аутентификации 401 или проблемах с оплатой и квотами так, будто это временные сетевые сбои.
  • При ограничении частоты запросов 429 и перегрузке 503 учитывайте Retry-After, если он указан, и используйте экспоненциальную задержку с ограничением числа попыток.
  • Не храните API-ключи в исходном коде и не включайте их в журналы, сообщения об исключениях или клиентские приложения.
  • Считайте ответ не в формате JSON или ошибку его разбора отдельной проблемой передачи данных либо прокси; собирайте только ограниченную по объему диагностическую информацию с удаленными чувствительными данными.
  • При передаче устойчивой проблемы в поддержку укажите модель, код ошибки, время, часовой пояс и очищенные от чувствительных данных сведения о запросе.
В этой статье (7)

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

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

В приведенных ниже процедурах используются JavaScript и понятия официальной библиотеки OpenAI, описанные в руководстве по кодам ошибок OpenAI. Это примерный шаблон кода, а не проверенная интеграция для промышленной среды.

Перед отладкой: защитите учетные данные и данные пользователей

Перед воспроизведением ошибки выполните следующие условия:

  • Храните API-ключ в серверном менеджере секретов или в переменной окружения. Не помещайте его в код браузера или мобильного приложения, систему контроля версий или обращение в службу поддержки.
  • Записывайте время запроса, категорию конечной точки, идентификатор модели, HTTP-статус и структурированный код ошибки, если он доступен.
  • Не записывайте в журналы заголовки Authorization, полные тела запросов и ответов или промпты с персональными данными.
  • Если для диагностики нужен промпт, сохраните очищенный от чувствительных данных пример или стабильный внутренний идентификатор запроса вместо исходного текста.
  • Ограничивайте длину диагностических данных. Прокси может вернуть большую HTML-страницу с ошибкой, а ответ вышестоящего сервиса — содержать данные, которые вы не планировали хранить.

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

Сначала диагностируйте ошибки аутентификации 401

Среди описанных случаев с кодом 401 — недействительная аутентификация, неверный API-ключ, отсутствие членства в организации и неразрешенный IP-адрес. Ошибка 403 может указывать на неподдерживаемую страну, регион или территорию.

Проверяйте следующее по порядку:

  1. Убедитесь, что сервер считывает нужный секрет и что он не был обрезан, не истек, не отозван и не заменен.
  2. Проверьте, что запрос отправляется на нужную конечную точку API и в нужный проект.
  3. Если используются идентификатор организации или список разрешенных IP-адресов, сверьте оба параметра с конфигурацией проекта.
  4. Проверьте, не отправляется ли запрос с другого исходящего IP-адреса в среде разработки, контейнере или хостинговой среде.
  5. Удалите значения учетных данных из отладочного вывода, прежде чем делиться журналами.

Не используйте автоматические повторы для ошибок 401 и 403. Повторная отправка запроса с теми же неверными учетными данными создаст лишние записи и может затруднить анализ инцидента. Исправьте конфигурацию и отправьте новый запрос.

Отличайте ограничение частоты запросов 429 от проблем с квотами и оплатой

Не всякая ошибка 429 означает «скоро попробуйте еще раз». В руководстве OpenAI описаны несколько разных случаев:

Категория ошибкиВозможное действиеПовторять автоматически?
Достигнут лимит запросовСнизить частоту запросов и следовать Retry-After, если он указанДа, с ограничениями
slow_downСнизить частоту запросов и увеличивать ее постепенноДа, осторожно
Закончился кредитный балансПополнить балансНет
Достигнут лимит расходов организации или проектаИзменить соответствующий лимитНет
Достигнут лимит использования организацииЗапросить увеличение одобренного лимита или обратиться в поддержкуНет

Цикл повторов должен учитывать HTTP-статус и конкретный код ошибки, а не обрабатывать все ответы 429 одинаково. Ограничьте число попыток, используйте экспоненциальную задержку и случайный интервал, чтобы несколько рабочих процессов не повторяли запросы одновременно. Если указан Retry-After, отдайте предпочтение этому времени ожидания, не превышая установленный вами максимальный интервал.

Учитывайте также ответы 503. В документации источника перегрузка модели обозначена кодом server_is_overloaded; перед повтором рекомендуется следовать Retry-After, если он указан. В библиотеке Python перегрузка может представляться как InternalServerError, а ответы 429 — как RateLimitError. Обработчики не должны исходить из того, что перегрузка всегда возвращается как 429.

Проверьте тайм-ауты и ошибки соединения

В официальной библиотеке Python для запросов, завершившихся по тайм-ауту, описан APITimeoutError, а для проблем с соединением — APIConnectionError. Основные направления диагностики:

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

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

Обрабатывайте некорректные ответы, не раскрывая содержимое

Под «некорректным ответом» могут подразумеваться разные проблемы: неверный запрос, приводящий к BadRequestError, ответ, не соответствующий ожидаемой схеме, или ответ прокси в виде HTML либо усеченных данных вместо JSON. В руководстве OpenAI BadRequestError описан как ошибка некорректного или неполного запроса; в качестве проверок рекомендованы обязательные параметры, кодировка, формат и размер.

При работе с HTTP-клиентами или промежуточным ПО проводите эти проверки отдельно:

  1. Перед разбором проверьте HTTP-статус и Content-Type.
  2. Выполняйте разбор JSON внутри блока обработки ошибок.
  3. Перед использованием проверьте наличие обязательных полей.
  4. Записывайте только статус, тип содержимого, длину ответа и ограниченный фрагмент с удаленными чувствительными данными, если это разрешено политикой.
  5. Не включайте API-ключ, полный промпт или весь ответ в сообщение об ошибке разбора.

Примерная обертка может выглядеть так:

async function parseSafeResponse(response) {
  const contentType = response.headers.get("content-type") || "";
  const body = await response.text();

  if (!contentType.toLowerCase().includes("application/json")) {
    throw new Error(`Unexpected response type: ${contentType}; length=${body.length}`);
  }

  try {
    return JSON.parse(body);
  } catch {
    throw new Error(`Invalid JSON response; length=${body.length}`);
  }
}

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

Пример обработчика ошибок с учетом конфиденциальности

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

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

try {
  const response = await client.responses.create({
    model: process.env.OPENAI_MODEL,
    input: "Redacted diagnostic input"
  });

  console.log({ ok: true, hasOutput: Boolean(response.output_text) });
} catch (error) {
  const details = {
    name: error?.name,
    status: error?.status,
    code: error?.code
  };

  if (error instanceof OpenAI.AuthenticationError) {
    console.error("Authentication failed", details);
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error("Rate limit or quota response", details);
  } else if (error instanceof OpenAI.APIConnectionError) {
    console.error("Connection failed", details);
  } else if (error instanceof OpenAI.APIError) {
    console.error("OpenAI API error", details);
  } else {
    console.error("Unexpected local error", { name: details.name });
  }
}

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

Когда обращаться в поддержку

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

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

Вопросы

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

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

Почему ошибка перегрузки OpenAI может возвращаться с кодом 503, а не 429?

В руководстве по ошибкам OpenAI перегрузка модели описана как ответ 503 с кодом server_is_overloaded. Обработчики ошибок должны проверять и статус, и код, а не считать перегрузку разновидностью ограничения частоты запросов.

Что записывать в журнал при ошибке аутентификации OpenAI?

Записывайте время, среду, категорию конечной точки, статус и очищенный от чувствительных данных код ошибки. Не записывайте API-ключ, заголовок Authorization, полное тело запроса или исходный пользовательский промпт.

Как диагностировать ответ с некорректным JSON?

Перед разбором проверьте HTTP-статус и Content-Type. Если это разрешено политикой, сохраните только ограниченные по объему диагностические данные с удаленными чувствительными сведениями. Также проверьте прокси и промежуточное ПО: они могут возвращать HTML, обрезать данные или изменять ответ.

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

Guides

Диагностика ошибок OpenAI API при сортировке обращений с подтверждением специалиста

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

阅读全文 →

Guides

Как диагностировать сбои OpenAI API при ответах на вопросы по документам

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

阅读全文 →

Guides

Как защитить ключи OpenAI API при сортировке обращений в поддержку

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

阅读全文 →

Guides

Как защитить ключи OpenAI API в системе вопросов и ответов по документам

Практический подход к защите ключей OpenAI API в приложении для вопросов и ответов по документам: разделяйте учетные данные, ограничивайте права доступа, маскируйте данные в журналах и безопасно меняйте ключи, сохраняя ссылки на источники.

阅读全文 →