Как безопасно диагностировать ошибки аутентификации, лимитов запросов, тайм-аутов и некорректных ответов OpenAI API
Практическое руководство с учетом конфиденциальности: как диагностировать ошибки аутентификации, ограничения частоты запросов, тайм-ауты и некорректные ответы OpenAI API, не раскрывая учетные данные и данные пользователей.
Кратко · 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 может указывать на неподдерживаемую страну, регион или территорию.
Проверяйте следующее по порядку:
- Убедитесь, что сервер считывает нужный секрет и что он не был обрезан, не истек, не отозван и не заменен.
- Проверьте, что запрос отправляется на нужную конечную точку API и в нужный проект.
- Если используются идентификатор организации или список разрешенных IP-адресов, сверьте оба параметра с конфигурацией проекта.
- Проверьте, не отправляется ли запрос с другого исходящего IP-адреса в среде разработки, контейнере или хостинговой среде.
- Удалите значения учетных данных из отладочного вывода, прежде чем делиться журналами.
Не используйте автоматические повторы для ошибок 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-клиентами или промежуточным ПО проводите эти проверки отдельно:
- Перед разбором проверьте HTTP-статус и
Content-Type. - Выполняйте разбор JSON внутри блока обработки ошибок.
- Перед использованием проверьте наличие обязательных полей.
- Записывайте только статус, тип содержимого, длину ответа и ограниченный фрагмент с удаленными чувствительными данными, если это разрешено политикой.
- Не включайте 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 в приложении для вопросов и ответов по документам: разделяйте учетные данные, ограничивайте права доступа, маскируйте данные в журналах и безопасно меняйте ключи, сохраняя ссылки на источники.