Обработка ошибок

Обрабатывайте ошибки API до того, как они достигнут пользователей.

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

Обзор краткого руководства См. рекомендации по повторной попытке

Последнее обновление: July 12, 2026. Examples использование safe placeholders и сделать не включить real API ключs или customer промпты.

Клиентское правило

Записывайте достаточно контекста для устранения сбоя, но никогда не записывайте необработанные ключи API, секреты, платежные данные или полные запросы клиентов.

Карта отказов

Начните с класса неудач.

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

Ошибки аутентификации

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

Квота превышена

Ошибки квоты означают, что запрос превысит лимит пакета для запросов, токенов или изображений. Сократите использование, дождитесь сброса или измените емкость пакета.

Сбои проверки

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

Сбои зависимостей

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

Поддержка эскалации

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

Форма ответа

Разберите объект ошибки, совместимый с OpenAI.

Check HTTP статус первый, затем branch на error.code для восстановление path.

{
  "error": {
    "message": "Missing or invalid API key.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

API статусы ошибок, коды, распространенные причины и следующие действия.
Статус	Коды	Общая причина	Следующее действие
400	недопустимый_json, недействительная_полезная нагрузка	Тело запроса недопустимо JSON или не соответствует схеме конечной точки.	Исправьте полезную нагрузку и повторите отправку только после прохождения проверки.
401	valid_api_key	Ключ API отсутствует, имеет неправильный формат или не распознан.	Проверьте токен носителя, переменную среды и префикс ключа.
402	подписка_неактивна, подписка_недоступна	Подписка, прикрепленная к ключу, не может получить доступ к API.	Прежде чем отправлять больше клиентского трафика, проверьте статус выставления счетов.
403	inactive_api_key, expired_api_key, ip_not_allowed, недостаточная_область	Ключ известен, но заблокирован статусом, сроком действия, политикой IP или областью действия.	Поменяйте или обновите ключ, а затем повторите попытку с необходимой областью.
429	запрос_quota_exceeded, token_quota_exceeded, image_quota_exceeded, quota_exceeded	Запрос превысит квоту пакета.	Уменьшите размер запроса, подождите периода квоты или выберите больший пакет.
429	rate_limit_exceeded	Клиент отправляет запросы быстрее, чем позволяет локальное ограничение скорости.	Уважайте Retry-After, если он присутствует, и используйте экспоненциальную отсрочку.
501	потоковая_не_включена	Запрошенная функция распознана, но не включена для конечной точки.	Отключите неподдерживаемый параметр или обратитесь в службу поддержки, если эта функция требуется.
5хх	Проверьте тело ответа	Ошибка внутренней зависимости или сетевого пути.	Повторите идемпотентную работу с отсрочкой, а затем увеличьте повторяющиеся ошибки с помощью контекста.

Повторить инструкции

Повторяйте только те сбои, которые можно восстановить.

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

Повторить попытку с отсрочкой

429rate_limit_exceeded, 408, 500, 502, 503, 504

Используйте ограниченную экспоненциальную задержку с джиттером. Уважайте повторную попытку — после того, как ответ включает ее.

Не повторять попытку без изменений

400, 401, 402, 403, 501

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

Повторить попытку после изменения емкости

429 кодов квот

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

async function callWithBackoff(runRequest) {
  for (let attempt = 0; attempt < 3; attempt += 1) {
    const response = await runRequest();

    if (response.ok) {
      return response;
    }

    const retryable = [408, 429, 500, 502, 503, 504].includes(response.status);
    if (!retryable) {
      return response;
    }

    const retryAfter = Number(response.headers.get("retry-after") ?? 0);
    const delayMs = retryAfter > 0 ? retryAfter * 1000 : 500 * 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }

  return runRequest();
}

Замечания по реализации

Ограничивайте количество повторных попыток, чтобы одно действие пользователя не могло вызвать всплеск трафика.

Добавьте джиттер в производственных клиентах, отправляющих одновременный трафик.

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

Захватите отредактированную диагностику до выхода из цикла повторных попыток.

Эскалация

Отправьте в поддержку контекст, в котором они могут действовать.

Хороший пакет эскалации сокращает сортировку, не раскрывая секреты, подсказки или данные клиентов.

Связаться со службой поддержки

Конечная точка, метод, код состояния и код ошибки.

Временная метка с часовым поясом и средой, в которой выполнялся вызов.

Маскированный префикс ключа API, а не необработанный ключ API.

Модель, пакет, состояние квоты и был ли повторен запрос.

Идентификатор запроса, идентификатор корреляции журналов и любой внешний идентификатор трассировки только по запросу службы поддержки.

Отредактированная форма полезных данных в случае неудачной проверки без подсказок или секретов клиента.

FAQ

Ошибка обработки вопросов.

Какую форму ошибки должен ожидать мой клиент?

/v1 API возвращает OpenAI-совместимый объект ошибки JSON с error.message, error.type и error.code. Ошибки проверки могут также включать сведения на уровне поля.

Должен ли я повторять каждый ответ 429?

Нет. Повторите короткие ответыrate_limit_exceeded, используя Retry-After, если он присутствует. Для кодов квот сократите использование, дождитесь сброса или выберите пакет с большей емкостью.

Что мне отправить в поддержку?

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

Бесплатные инструменты

Отладка ошибок с помощью бесплатных инструментов

Ищите коды ошибок, декодируйте ответы 429, моделируйте повторные попытки и планируйте мониторинг ограничения скорости.

Просмотреть все инструменты

Поиск кода ошибки

Найдите коды ошибок unlimitedcodex, статусы HTTP, рекомендации по повторным попыткам и действия по восстановлению.

429 Декодер

Вставьте тело ответа 429 и заголовки, чтобы классифицировать ограничение скорости и давление квоты и просмотреть рекомендации по повторной попытке.

Повторить симулятор

Настройте параметры отсрочки и повтора, чтобы увидеть смоделированные результаты, и скопируйте фрагмент обработчика повтора.

Планировщик лимитов ставок

Запланируйте настройки отсрочки и контрольный список мониторинга квот, исходя из ожидаемого RPS и размера команды.