Ошибки OpenAI API после смены шлюза: 429, 402 и чем они отличаются

Ошибки OpenAI API после смены шлюза: как читать 429 и 402
Ошибки OpenAI API после смены шлюза: как читать 429 и 402

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

Ниже оба контракта ошибок рядом, парные карточки и обработчик с тестами, который понимает оба маршрута.

Почему старый обработчик врёт после переезда

Интеграция годами ходила в api.openai.com, потом из России прямой маршрут стал недоступен: в списке поддерживаемых стран OpenAI API России нет, а запрос из неподдерживаемого региона, по справочнику кодов OpenAI, получает 403. Команда меняет base_url на совместимый шлюз, например на https://api.provod.ai/v1, подставляет новый ключ, и первый запрос проходит.

А обработчик ошибок остаётся прежним. Он писался под один контракт, где поле code лежит внутри объекта error, где про оставшиеся запросы рассказывают заголовки x-ratelimit-* и где 402 не бывает вообще. После смены маршрута те же ветки if status == 429 начинают срабатывать на совсем другие причины.

Главное правило статьи: по совпадению HTTP-кода нельзя делать одинаковый вывод о повторе и о списании денег для разных маршрутов. Решение принимается по паре «статус плюс публичный код ошибки», а код каждый маршрут кладёт в своё место.

Если вы искали «почему не работает чат GPT в России»: вход в веб-чат ChatGPT устроен иначе, ему посвящена отдельная статья серии. Здесь только API.

Два контракта ошибок рядом

Всё, что ниже, взято из опубликованных справочников на 12 ноября 2026 года, живых ответов я в этот раздел не подкладывал.

Прямой OpenAI API. Ошибка приходит объектом error с полями message, type, code и param. Вот что справочник OpenAI пишет про коды, которые нас интересуют:

  • 401 означает проблемы с ключом: опечатку, отозванный ключ, ключ от другого проекта или IP вне разрешённого списка;
  • 403 приходит, если страна или регион запроса не поддерживается;
  • 429 объединяет сразу несколько разных причин, и это самое важное место контракта;
  • 500 означает внутреннюю ошибку, а 503 с кодом server_is_overloaded говорит о перегрузке модели; оба повторяют с паузой.

Под 429 у OpenAI лежат разные причины: превышение лимита запросов, иногда без отдельного кода, только с сообщением «Rate limit reached for requests»; код slow_down, когда трафик вырос слишком резко, даже если формально вы укладываетесь в лимит; целая группа денежных причин: credit_balance_exhausted при закончившихся кредитах, project_spend_limit_exceeded и organization_spend_limit_exceeded при упёршемся лимите расходов, organization_usage_limit_exceeded при месячном потолке, который назначает сам OpenAI. У денежных ошибок error.type может быть insufficient_quota, и повторять их бессмысленно, пока не поменялись кредиты или лимиты.

Для временных лимитов OpenAI отдаёт заголовок Retry-After и, по странице о лимитах, набор x-ratelimit-*: сколько запросов и токенов осталось и когда счётчик сбросится.

Шлюз Provod. По справочнику ошибок Provod обычная ошибка Chat Completions тоже приходит объектом error с полями code, message, param и type, так что на первый взгляд всё знакомо. Отличия начинаются в деталях:

  • 402 означает проблему с доступным балансом рабочего пространства; документация просит сначала посмотреть доступный баланс и активные резервы, дождаться их освобождения и только потом пополнять счёт или уменьшать запрос;
  • 403 бывает с кодом FIRST_TOP_UP_REQUIRED и ссылкой topUpUrl на первое пополнение, при этом документация отдельно оговаривает, что далеко не каждая 403 про деньги;
  • 429 нужно разбирать по верхнеуровневому code: при API_KEY_SPEND_LIMIT_EXCEEDED это лимит расходов конкретного ключа, а любой другой 429 считается временным ограничением;
  • 5xx разбирают по публичному коду, например 503 MODEL_NOT_AVAILABLE, с оглядкой на то, начался ли уже результат.

У ошибок оплаты Provod поля лежат в корне JSON рядом с объектом error, и документация прямо предупреждает, что структура бывает не вложенной. Обработчик, который ищет код только в error.code, лимит ключа просто не увидит.

Ошибки OpenAI API и шлюза Provod: где лежит поле code
Ошибки OpenAI API и шлюза Provod: где лежит поле code

Пара первая: упёрлись в лимит скорости

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

Прямой OpenAI API. Статус: 429. Где код: в error.code, например slow_down, а у обычного превышения лимита отдельного кода может и не быть, тогда остаётся error.type со значением rate_limit_error и текст сообщения. Чем ждать: заголовком Retry-After, если он пришёл, а состояние счётчиков видно в x-ratelimit-remaining-requests, x-ratelimit-remaining-tokens и соседних заголовках. Что делать: подождать не меньше Retry-After, иначе экспоненциальная задержка со случайным разбросом и потолком попыток, и снижать темп; при slow_down наращивать нагрузку постепенно. Что писать в журнал: статус, error.code и error.type, значение Retry-After, остатки из x-ratelimit-*, ID запроса из заголовка x-request-id.

Шлюз Provod. Статус: 429. Где код: в верхнеуровневом code, и если это не API_KEY_SPEND_LIMIT_EXCEEDED, перед вами временное ограничение. Чем ждать: Retry-After, если он есть; страница «Лимиты и повторы» прямо пишет «если он есть», так что на его обязательное присутствие рассчитывать нельзя. Заголовки x-ratelimit-* в документации Provod не описаны, и числовые лимиты запросов в минуту там тоже не опубликованы. Что делать: ограниченные повторы до начала результата, после первого токена автоматических повторов не запускать. Что писать в журнал: статус, публичный код, время с часовым поясом, модель, название ключа и его маскированный префикс, ID запроса, если его показал клиент или раздел использования.

Код, который читал остаток запросов из x-ratelimit-remaining-requests и по нему притормаживал очередь, после переезда получит пустое значение. Решите заранее, что он делает в этом случае: падает, считает остаток неизвестным или переходит на чистую экспоненциальную задержку. Я бы выбрал последнее.

Пара вторая: закончились деньги или бюджет

Здесь различий больше.

Прямой OpenAI API. Статус: 429, тот же, что у лимита скорости. Где код: в error.code: credit_balance_exhausted, project_spend_limit_exceeded, organization_spend_limit_exceeded или organization_usage_limit_exceeded; error.type может быть insufficient_quota. Чем ждать: ничем, повтор не поможет, пока не пополнены кредиты или не поднят лимит. Лимит расходов организации, по справочнику, сбрасывается в начале месяца. Что делать: остановить повторы, поднять тревогу, пополнить баланс или поменять лимит в кабинете OpenAI. Что писать в журнал: статус, error.code, error.type, проект и время.

Шлюз Provod, и здесь уже два разных случая с разными статусами.

Если упёрся бюджет ключа, придёт 429 с верхнеуровневым code API_KEY_SPEND_LIMIT_EXCEEDED. По странице о лимитах ключа в ответе есть период, лимит, уже списанная и зарезервированная суммы, оценка нового запроса, валюта и resetAt. Модель при этом не запускалась. Делать тут нужно одно из двух: ждать resetAt или поднять лимит в разделе API-ключей. Время сброса берите из ответа, а resetAt не путайте с Retry-After, это разное.

Если не хватило денег на балансе рабочего пространства, придёт 402. Поле code на этот случай документация отдельно не называет, зато описывает поля верхнего уровня с текущей и требуемой суммой. Тут есть тонкость с резервами: перед каждым запросом Provod откладывает оценку его стоимости, и по разделу о балансе доступная сумма равна общей минус активные резервы. Поэтому 402 бывает и при положительном общем балансе, когда параллельно идёт много запросов. Документация советует сначала дождаться освобождения резервов и проверить баланс снова и только потом пополнять.

У OpenAI все денежные беды живут под 429 и отличаются только кодом в теле. У Provod 429 с API_KEY_SPEND_LIMIT_EXCEEDED означает ваш собственный потолок на ключ, а нехватка денег на балансе приходит отдельным статусом 402. Ветка if status == 429: retry() в первом случае зря потратит пару попыток, а 402 старый код, скорее всего, вообще уронит в общую ветку «неизвестная ошибка».

Ошибки OpenAI API про деньги: 429 у OpenAI и 402 у Provod
Ошибки OpenAI API про деньги: 429 у OpenAI и 402 у Provod

Один обработчик на два маршрута

Пример документационный: он написан по справочникам OpenAI и Provod и по описанию официального Python SDK, против живого API для статьи не запускался. Идентификатор модели openai/gpt-5.4 взят из примера в документации Provod, актуальный список лежит в каталоге моделей.

Сначала про встроенные повторы SDK. По описанию библиотеки openai-python она по умолчанию сама повторяет ошибки соединения, 408, 409, 429 и 5xx дважды с короткой экспоненциальной задержкой. Для шлюза это значит, что 429 с исчерпанным бюджетом ключа будет отправлен ещё два раза, прежде чем ваш код вообще увидит исключение. Я бы выключал встроенные повторы и решал всё в одном месте:

import os, random, time, logging from openai import OpenAI, APIStatusError, APIConnectionError log = logging.getLogger("llm") client = OpenAI( base_url="https://api.provod.ai/v1", api_key=os.environ["PROVOD_API_KEY"], max_retries=0, # повторы решаем сами ) class BudgetStop(Exception): """Деньги или лимит: повтор не поможет, нужен человек.""" def read_error(exc: APIStatusError): try: body = exc.response.json() except ValueError: body = {} nested = body.get("error") or {} code = body.get("code") or nested.get("code") # Provod кладёт код и в корень return code, nested.get("type"), body MONEY_CODES = { "API_KEY_SPEND_LIMIT_EXCEEDED", # Provod: бюджет ключа "credit_balance_exhausted", # OpenAI: кредиты "project_spend_limit_exceeded", "organization_spend_limit_exceeded", "organization_usage_limit_exceeded", } def ask(messages, model="openai/gpt-5.4", attempts=4, cap=30.0): for n in range(attempts): try: return client.chat.completions.create(model=model, messages=messages) except APIStatusError as e: code, etype, body = read_error(e) retry_after = e.response.headers.get("retry-after") log.warning("status=%s code=%s type=%s request_id=%s retry_after=%s", e.status_code, code, etype, e.request_id, retry_after) if code in MONEY_CODES or etype == "insufficient_quota" or e.status_code == 402: raise BudgetStop(body) from e if e.status_code == 429 or e.status_code >= 500: delay = float(retry_after) if retry_after and retry_after.isdigit() \ else min(2 ** n + random.random(), cap) time.sleep(delay) continue raise # 400, 401, 403 и прочее чинится в коде или в кабинете except APIConnectionError: # ответа нет, но это не доказывает, что запрос не принят log.error("no HTTP response, check usage before retry") raise raise RuntimeError("retries exhausted")

Код ошибки ищется в двух местах, в корне JSON и внутри error, так один и тот же обработчик понимает оба маршрута. Деньги и бюджет вынесены в отдельное исключение: реагировать на них должен человек или биллинг, а не очередь повторов. Обрыв соединения без HTTP-ответа я не повторяю автоматически: справочник Provod прямо пишет, что отсутствие ответа не подтверждает, что запрос не был принят, и сначала нужно проверить раздел использования, время и модель. Retry-After здесь читается только в секундах; если ваш маршрут присылает его датой, допишите разбор.

Пример не потоковый. Для стрима после первого токена автоматических повторов нет вообще, поток Chat Completions считается завершённым только после [DONE], а частичный результат может быть оплачен.

Как проверить обработчик до продакшена

import httpx, pytest from openai import OpenAI from mymodule import ask, BudgetStop # модуль с обработчиком выше def fake_client(status, body, headers=None, calls=None): def handler(request): if calls is not None: calls.append(request) return httpx.Response(status, json=body, headers=headers or {}) return OpenAI(base_url="https://api.provod.ai/v1", api_key="test", max_retries=0, http_client=httpx.Client(transport=httpx.MockTransport(handler))) def test_key_budget_stops_at_once(monkeypatch): calls = [] body = {"code": "API_KEY_SPEND_LIMIT_EXCEEDED", "resetAt": "2026-11-13T00:00:00+03:00"} monkeypatch.setattr("mymodule.client", fake_client(429, body, calls=calls)) with pytest.raises(BudgetStop): ask([{"role": "user", "content": "ping"}]) assert len(calls) == 1 # ни одного лишнего запроса

По тому же шаблону я бы добавил ещё четыре теста:

  • 429 без денежного кода и с Retry-After: 2: обработчик ждёт две секунды и повторяет, а после исчерпания попыток отдаёт ошибку приложению;
  • 429 без Retry-After: задержка растёт и не превышает потолка;
  • 402: ни одного повтора, сразу BudgetStop;
  • 429 с credit_balance_exhausted внутри error, как у прямого OpenAI: тоже BudgetStop, значит, ветка понимает и вложенный код.

Тесты стоит прогнать отдельно с max_retries=0 и с настройкой SDK по умолчанию. Разница в числе запросов на один и тот же 429 покажет, кто решает о повторе: ваш код или библиотека. После обновления SDK тест полезно гонять заново.

Ошибки OpenAI API в тестах: обработчик останавливает лишние повторы
Ошибки OpenAI API в тестах: обработчик останавливает лишние повторы

Что настроить в Provod под этот обработчик

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

Задал бы этому ключу лимит расходов на день, неделю или месяц. Текущий остаток можно спросить запросом GET https://api.provod.ai/v1/key: в ответе будут limit, limit_remaining и limit_reset, а если лимит не задан, эти поля придут как null. Часовой пояс сброса, UTC или Москва, там же в поле time_zone. Тогда 429 с API_KEY_SPEND_LIMIT_EXCEEDED однозначно значит «упёрлись в бюджет этой интеграции», а сбой одного сервиса не съедает деньги остальных.

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

Коротко

У прямого OpenAI и лимит скорости, и закончившиеся кредиты приходят как 429, а различаются они только кодом и типом внутри объекта error.

У Provod нехватка доступного баланса приходит как 402, а 429 с API_KEY_SPEND_LIMIT_EXCEEDED означает исчерпанный лимит конкретного ключа с временем сброса в resetAt.

Код ошибки шлюза может лежать в корне JSON, поэтому обработчик должен искать его и там, и внутри error.

Заголовки x-ratelimit-* документированы только у прямого OpenAI, а Retry-After у шлюза приходит не всегда, и код должен переживать его отсутствие.

Проверить всё это на своей интеграции проще всего на отдельном ключе: выпустите его на странице API Provod, поставьте маленький лимит и посмотрите, сколько запросов ваш код отправит, получив первый 429.

Подробнее:

11