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

Сначала определите, произошла ли ошибка до обращения к модели, во время маршрутизации или у поставщика. HTTP-статус и безопасный код ошибки полезнее общего исключения интерфейса. Сохраните ID запроса и время; удалите заголовки Bearer и закрытые входные данные перед передачей диагностики.

Пример ответа

{"error":{"type":"invalid_request_error","code":"model_not_found","message":"Unknown or disabled model."}}

Что проверить в запросе

Проверьте API-хост, выбранный путь, ID включённой модели и тип токена. Токен Partner не разрешает запросы к моделям. Файловый вход должен соответствовать полям выбранного протокола; для PDF в Responses file_data содержит data:application/pdf;base64, перед закодированными байтами.

Структура сведений в ответе соответствует выбранному формату совместимости. Часть данных поставщика заменяется безопасным сообщением. Обращайтесь в поддержку с ID запроса и кодом ошибки, без учётных данных и конфиденциальных входов компании.

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

Разбор неполных потоков компании

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

Если у неуспешного потока нет счётчиков поставщика, usage помечается как неизвестное для проверки; автоматическое списание по оценке сетевых байтов не выполняется. Полученные счётчики поставщика сохраняются. Не назначайте автоматический платный повтор только ради более понятной ошибки или записи usage.

Ошибки специализированного Images API

Неоднозначный результат у поставщика в операции изображений компании не должен превращаться в новый автоматический платный запрос. Проверяйте сохранённое состояние даже после HTTP 200/202. Для истории и поиска без записи сохраняйте исходный ключ и контекст сотрудника; не меняйте сотрудников или ключи для обхода конфликта. outcome_unknown и review_required требуют оператора, а retrieval_failed разрешает только повтор скачивания результата. Текущие правила операций имеют приоритет над общими советами о повторах для этих эндпоинтов.

Подробности ошибки поставщика и проверка сессии

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

Недопустимый идентификатор сессии вызывает ошибку валидации: исправьте поле, а не повторяйте запрос без изменений. Уже заданная распознанная сессия в metadata.user_id принимается с приоритетом session_id, X-Session-ID, распознанная сессия в метаданных, prompt_cache_key, затем начальное содержимое. Разные переданные значения не вызывают ошибку несовпадения сессий. Обычный идентификатор пользователя сохраняется, не превращаясь в идентификатор диалога. Маршрут, использующий это занятое поле, не может одновременно вставить управляемую сессию; внешняя привязка в таком случае не обещается. Неверные типы метаданных или повторяющиеся ключи объекта по-прежнему могут вызывать ошибку валидации на маршруте с передачей сессии через метаданные. Остальные метаданные сохраняются. Наличие идентификатора сессии не доказывает, что платный запрос с тайм-аутом не был принят. Сохраните X-Request-ID и проверьте существующий запрос перед повтором.

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