Код, который обрабатывает только идеальный ответ, уже содержит будущую ошибку продакшена. Он проходит ревью, проходит демо, работает неделю - и падает в тот момент, когда провайдер вернул 429 или имя модели перестало приниматься. Успешный запрос выглядит как доказательство устойчивости, но это ложное доказательство. Он показывает только то, что в этот раз всё совпало.
Дальше - разбор минимального адаптера, который устроен наоборот: сначала описывает предсказуемую неудачу и дешёвую смену конфигурации, а уже потом прикладную логику. Три контрактных сценария, которые нужны такому адаптеру, - обычный ответ, ошибка и замена модельной конфигурации. Каждый из них проверяется отдельно, а результат складывается в журнал.
Журнал и есть смысл упражнения: он должен развести точки интеграции на стабильные (клиент справляется сам) и требующие обработки (без нашего кода они превращаются в инцидент). Пока такого разделения нет, «работает» и «устойчиво» остаются одним и тем же словом.
Платите в рублях за GPT API без наценки на токены через provod.ai
Почему успешный ответ - плохой свидетель?
Дефолт, с которым я спорю, звучит так: «раз запрос вернул 200 и осмысленный текст, интеграция готова». Готова - обрабатывать ровно один сценарий из многих. openai llm api - это поверхность с сетевыми сбоями, лимитами, кодами статуса и меняющимся списком моделей. Устойчивость измеряется не удачным вызовом, а тем, воспроизводится ли ошибочный сценарий и что происходит при смене конфигурации.
Отсюда критерий, который можно проверить и опровергнуть: если смена конфигурации или обработка ошибки требует правки прикладной логики, адаптер свой контракт не выполнил. Это проверяемо. Если для перехода на другую модель приходится трогать функцию, которая считает скидку или собирает промпт, - изоляция не состоялась.
Хорошая новость: официальный open ai sdk уже даёт материал, на котором такой контракт строится. Классификацию ошибок изобретать не нужно - open ai библиотека задала её за нас, остаётся сделать её наблюдаемой в своём коде.
Библиотека openai даёт нужный материал из коробки
По данным README репозитория openai/openai-python (доступ 2026-07-18), библиотека openai даёт структурированную иерархию исключений с корнем openai.APIError. Она делится на openai.APIConnectionError - сетевые, прокси- и SSL-сбои на пути к API, - и openai.APIStatusError для любого не-2xx ответа; последний открывает .status_code и .response.
Ниже по иерархии - отдельно импортируемые подклассы под конкретные коды: BadRequestError (400), AuthenticationError (401), PermissionDeniedError (403), NotFoundError (404), UnprocessableEntityError (422), RateLimitError (429) и InternalServerError (>=500) (Developer Platform, доступ 2026-07-18). Отдельно стоит APITimeoutError - он поднимается, когда запрос вышел за настроенный таймаут.
Клиент к тому же сам повторяет часть сбоев. По README он по умолчанию делает 2 повтора с коротким экспоненциальным откатом для connection-ошибок, а также для HTTP 408, 409, 429 и любого ответа >=500. Это настраивается глобально через OpenAI(max_retries=N) или на конкретный вызов через .with_options(max_retries=N). Дефолтный таймаут запроса - 10 минут, меняется через OpenAI(timeout=20.0) или гранулярно httpx.Timeout(...); таймаутнутый запрос всё ещё попадает под дефолтные повторы.
Эти имена и дефолты - не музейный экспонат. По данным PyPI (доступ 2026-07-18) актуальная версия пакета openai - 2.46.0, выпущена 2026-07-17. То есть иерархия исключений и дефолты выше относятся к текущему релизу клиента, а не к устаревшему; перед своим прогоном сверьте номер версии заново - README живёт вместе с релизами.
Минимальный контрактный адаптер: код и структура
Установка стандартная для openai api python: pip install openai, дальше импорт клиента и нужных классов ошибок. Идея адаптера в одном: вся работа, которую open ai python делает в сервисе, - конфигурация модели и разбор ошибок - живёт в одном месте, а прикладной код видит только узкий метод и понятные исключения своего домена.
Ключевой факт, который делает это возможным: параметр model - обязательный явный аргумент каждого вызова (client.responses.create(model="...", input=...)), а не скрытое состояние клиента (README и API reference, доступ 2026-07-18). Значит, выбор модели можно свести к одному значению конфигурации, а не размазывать по бизнес-логике. Клиентские настройки - api_key, base_url, timeout, max_retries - задаются один раз при создании OpenAI(...).
from openai import ( OpenAI, APIConnectionError, APITimeoutError, RateLimitError, AuthenticationError, APIStatusError, )
class AdapterError(Exception): """Доменная ошибка, которую видит прикладной код."""
class AdapterConfig(AdapterError): """Проблема ключа/доступа/имени модели - чинится в конфиге."""
class AdapterBusy(AdapterError): """Временная перегрузка, безопасно повторить позже."""
class ModelAdapter: def **init**(self, api\_key, base\_url, model, timeout=20.0, max\_retries=2): # вся модельная конфигурация изолирована здесь self.\_client = OpenAI( api\_key=api\_key, base\_url=base\_url, timeout=timeout, max\_retries=max\_retries, ) self.\_model = model
def complete(self, prompt: str) -> str: try: resp = self.\_client.responses.create( model=self.\_model, input=prompt, ) return resp.output\_text except AuthenticationError as e: raise AdapterConfig("ключ, членство в организации или IP") from e except RateLimitError as e: raise AdapterBusy("лимит или квота, повторить с откатом") from e except APITimeoutError as e: raise AdapterBusy("таймаут, повторить позже") from e except APIStatusError as e: if e.status\_code >= 500: raise AdapterBusy(f"сервер {e.status\_code}") from e raise AdapterConfig(f"клиентская ошибка {e.status\_code}") from e except APIConnectionError as e: raise AdapterBusy("сеть/прокси/SSL до API") from e
Прикладная логика теперь ловит AdapterConfig и AdapterBusy, а не сырые классы SDK. Цепочка исключений при этом не теряется: from e сохраняет исходный traceback для логов. Так выглядит рабочий open ai api code, где различия провайдера не протекают наверх. И правило простое: ни один openai api client в проекте не создаётся за пределами этого класса - openai client живёт в конструкторе адаптера и больше нигде.
У клиента при этом не один контракт, а несколько поверхностей, и каждая заслуживает своего сценария. openai responses api отвечает за генерацию текста; openai embeddings api возвращает векторы; openai audio api работает со звуком. Форматы ответов и наборы ошибок у них разные, поэтому один пройденный тест на генерацию не переносится автоматически ни на api openai embeddings, ни на звук.
Изоляция поставщика тут не косметика: она заранее удешевляет замену маршрута. Тот же адаптер позже перенаправляется на совместимый российский эндпоинт правкой одного значения base_url, а не прикладного кода - именно ради этого мы и вынесли конфигурацию в конструктор.
Три контрактных сценария: что именно проверяем?
Метод простой и намеренно узкий. Три теста, каждый фиксирует ожидаемое поведение, а не «работает вообще».
Сценарий 1 - обычный ответ. Мокаем responses.create, проверяем, что complete вернул строку и не тронул конфигурацию. Это база, но она не доказывает устойчивость сама по себе.
Сценарий 2 - ошибка. Заставляем клиент поднять RateLimitError и AuthenticationError, проверяем, что адаптер превратил их в AdapterBusy и AdapterConfig соответственно. Здесь важна честная граница: по документации 429 означает две разные вещи - троттлинг по скорости и исчерпание квоты/биллинга. Пейсинг-429 повторяют с откатом, квота-429 требует сначала разобраться с оплатой. А вот по какому именно полю ответа различать причину, документация прямо не проговаривает - это надо снять с живого ответа в своём контрактном тесте, а не выдумывать.
Сценарий 3 - смена конфигурации. Пересобираем адаптер с другим model и другим base_url и убеждаемся, что метод complete и вся прикладная обвязка не изменились ни на строку. Если для смены пришлось редактировать бизнес-логику - тест красный, тезис фальсифицирован, адаптер не сделал свою работу.
Стоит развести, что здесь твёрдо, а что нет. Твёрдо: контрактный тест фиксирует ожидаемый ответ и ожидаемую ошибку адаптера - это его прямая работа. Правдоподобно, но не доказано: прямой вызов без адаптера связывает вас с поставщиком сильнее. А тела ответов и коды, которые вернёт именно ваша среда, до запуска не знает никто - эта статья в том числе.
Смена модели - это отказ, а не косметика
Хардкод имени модели - настоящий вектор отказа продакшена, и это не мнение. По политике депрекации OpenAI (Developer Platform, доступ 2026-07-18) есть состояния жизненного цикла: «Deprecated» - модель перестаёт принимать новые запросы; «Sunset/Shut down» - после даты отключения недоступна полностью; «Legacy» - не обновляется, но ещё вызывается. После shutdown вызов по старому имени падает.
Сроки предупреждения там - минимумы: не менее 6 месяцев для общедоступных моделей, не менее 3 месяцев для специализированных вариантов и порядка 2 недель для preview; вопросы безопасности и комплаенса могут сократить срок. Для конкретной модели фактический срок может быть больше минимума - поэтому подавать эти числа как обещание для каждой модели нельзя.
Практический вывод для дизайна: если openai api models перечисляются и меняются, а имя модели - обязательный аргумент вызова, держи его как одно значение конфигурации. Тогда переезд с одной модели на другую - это правка конфига и один прогон сценария 3, а не раскопки по кодовой базе. Список open ai api models стоит перепроверять перед релизом, а не считать вечным.
Смена модели упирается и в деньги. openai api pricing различается между моделями, поэтому при переезде смотрят не только качество, но и openai api price за токены. Для российской команды к open ai api price добавляется второй вопрос - чем платить, - и он решается на том же уровне конфигурации, что и первый: provod.ai, российский аналог OpenRouter, подключается тем же клиентом и тем же openai base url, отдаёт цены моделей без своей наценки и держит один рублёвый баланс. Практически это выглядит так:
# было: официальный маршрут client = OpenAI(api\_key=OPENAI\_KEY)
# стало: совместимый маршрут, прикладной код не меняется client = OpenAI( api\_key=PROVOD\_KEY, base\_url="https://api.provod.ai/v1", )
Важная оговорка по границе: совместимый маршрут покрывает только базовый API и уступает по возможностям официальным инструментам конкретного поставщика. Обратимость здесь есть, но она не бесплатна по фичам - и это тоже строчка журнала, а не то, что держат в голове.
Журнал контрактных сценариев: от «работает» до «устойчиво»
Журнал - это то, что метод обязан оставить после себя: список из двух колонок. Слева стабильные точки, где клиент справляется сам: сетевые сбои, 408/409/429 и >=500 он повторяет по умолчанию (2 раза), таймаут ловится своим классом. Справа - точки, требующие обработки: 401 клиент не повторяет, и без нашего маппинга он всплывёт наверх сырым; квота-429 нельзя молча ретраить; смена model/base_url обязана проходить без правки бизнес-логики.
Именно журнал отделяет «работает» от «устойчиво». Пустой лог с одним зелёным тестом на успешный ответ - это ровно та ситуация, с которой статья началась. Заполненный лог с воспроизведёнными ошибками и подтверждённой сменой конфигурации - это то, что можно нести в ревью.
Разработчики на других стеках здесь тянутся к своим обёрткам - например к ai sdk openai в JS-экосистеме, - но принцип не про язык. Для Python роль обёртки играет наш адаптер поверх официальной библиотеки, и контракт у него тот же: наблюдаемая ошибка плюс дешёвая смена конфигурации.
Чего этот подход не решает
Тесты не доказывают поведение всех моделей и всех поставщиков - они фиксируют контракт вашего адаптера, и только его. Три сценария - это гипотеза о достаточности, а не теорема; если у вас есть эмбеддинги и звук, добавляйте сценарии под каждую поверхность отдельно.
Адаптер не отменяет стоимости кода: это лишний слой, и это принятая плата за снижение цены смены поставщика. Он не заменяет наблюдаемость на уровне инфраструктуры, не решает вопрос гарантированной ёмкости под повторяющимися 503 (официальная рекомендация тут - смотреть статус-страницу и рассматривать Scale Tier) и не превращает совместимый маршрут в источник эксклюзивных функций конкретного вендора.
И последнее, о чём стоит сказать прямо: ни «adapter pattern», ни «contract testing» в документации OpenAI как рекомендованная стратегия интеграции не названы. Это моя инженерная позиция, а не ссылка на первоисточник, - спорить с ней можно и нужно.
FAQ
Нужен ли адаптер для одного скрипта на выходные?
Нет. Прямой вызов через python openai там дешевле. Адаптер окупается, когда прикладная логика переживёт смену модели или поставщика хотя бы раз.
Клиент и так повторяет 429 - зачем ещё обработка?
Потому что квота-429 повторять бессмысленно, а сетевой обрыв после исчерпания повторов всё равно всплывёт. Клиент делает 2 повтора по умолчанию, дальше отвечаете вы.
Можно ли обойтись без своих классов ошибок?
Можно ловить сырые классы SDK, но тогда прикладной код снова знает про поставщика. Доменные AdapterConfig/AdapterBusy и есть та граница, ради которой всё затевалось.
Как проверить смену провайдера, не ломая прод?
Собрать адаптер с тестовым base_url и прогнать сценарий 3. Если complete и обвязка не изменились - обратимость подтверждена на этом маршруте.
Где взять точные ошибки и коды?
Из живого прогона в вашей среде. openai python api и документация дают классы и дефолты, но конкретные тела ответов снимаются тестом.
provod.ai — выбирайте по результату, а не по сложности доступа
Проверяйте несколько моделей на одном сценарии и переключайтесь на ту, которая лучше решает задачу: интеграция, команда и платёжный контур при этом не меняются.
В одном каталоге — актуальные модели для текста и медиа: GPT от OpenAI, Claude от Anthropic, Gemini от Google, Grok от xAI, DeepSeek, Qwen, GLM, Kimi и MiniMax; для изображений — Nano Banana 2 Pro и GPT Image; для видео — последние версии Seedance, Kling, Veo и Google Omni. Также доступны модели для reasoning, поиска, документов, эмбеддингов, музыки и аудио.
Сравнение остаётся честным по цене: каждый вариант считается 1:1 по официальному тарифу провайдера, без собственной надбавки provod.ai.
Найдите лучшую модель для задачи: форма регистрации · цены на модели · защита данных по 152-ФЗ · главная provod.ai
Источники
- openai/openai-python, GitHub, доступ 2026-07-18 - иерархия исключений, повторы, таймаут, явный параметр
model, клиентская конфигурация иbase_url. - OpenAI Developer Platform, Error codes, доступ 2026-07-18 - классы по кодам, смысл 401/429/500/503, различие квоты и пейсинга.
- OpenAI Developer Platform, Deprecations, доступ 2026-07-18 - состояния жизненного цикла и минимальные сроки уведомления.
- OpenAI Developer Platform, Python API reference, доступ 2026-07-18 - явный
modelи разделение конфигурации клиента. - PyPI, пакет openai, доступ 2026-07-18 - версия 2.46.0, выпуск 2026-07-17.