Provider returned error: что значит ошибка OpenRouter и как её обойти

Ваш запрос дошёл до OpenRouter, а сломалось дальше — у поставщика модели. Разбираем, что лежит внутри ответа и как переключить маршрут.

Получить ключ Что делать

/ Короткий ответ

Что это значит

Provider returned error — ответ OpenRouter с кодом 502: агрегатор принял ваш запрос, передал его поставщику модели, а тот вернул ошибку. Ключ, баланс и формат запроса здесь обычно ни при чём — сбой на следующем звене. В теле ответа рядом с текстом лежит сырой ответ поставщика и его имя, и именно там написано, что случилось на самом деле.

Чаще всего внутри перегрузка или таймаут у поставщика, его модерация, превышение его лимита контекста или параметр, который этот конкретный поставщик не поддерживает. У одной модели на OpenRouter бывает несколько поставщиков, и ошибка может касаться только одного из них — остальные в этот момент работают.

Поэтому лечится двумя способами. Первый — повтор через несколько секунд: если сбой временный, следующий запрос уйдёт другому поставщику. Второй — управление маршрутом: поле provider с order и allow_fallbacks задаёт, кого пробовать первым и разрешено ли переключаться. Если ошибка повторяется на одной модели у всех поставщиков, меняйте модель, а не настройки.

/ Почему

Откуда берётся ошибка

Перегрузка поставщика. Внутри сырого ответа overloaded или 529: у поставщика нет мощности, через несколько секунд обычно проходит.
Таймаут на стороне поставщика. Длинный запрос без стриминга не уложился в его лимит времени; у OpenRouter это может прийти и как 408.
Лимит контекста конкретного поставщика. У одной и той же модели разные поставщики дают разный максимум контекста, и ваш запрос влез не ко всем.
Неподдерживаемый параметр. Например, формат ответа или инструменты, которые у этого поставщика не реализованы; другой поставщик тот же запрос примет.
Модерация у поставщика. Запрос прошёл OpenRouter, но отклонён фильтром поставщика; смена маршрута иногда помогает, смягчение запроса — надёжнее.

/ Тексты ошибок

Что лежит внутри Provider returned error

Текст ошибки	Причина	Что делать
502 Provider returned error, внутри overloaded	Перегрузка у поставщика модели	Повтор с паузой 2–5 секунд, allow_fallbacks: true
502 Provider returned error, внутри timeout	Поставщик не ответил в свой лимит времени	Включить стриминг, сократить запрос, другой поставщик через provider.order
502 Provider returned error, внутри context length	Контекст больше лимита этого поставщика	Сократить историю или выбрать поставщика с большим контекстом
502 Provider returned error, внутри unsupported	Параметр не поддержан у этого поставщика	Убрать параметр или задать order с поставщиком, который его умеет
408 Request timeout	Ответ не пришёл в отведённое OpenRouter время	Стриминг, повтор, увеличить timeout в клиенте

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

/ Что делать

Порядок действий

Прочитайте сырой ответ поставщика

В JSON ошибки кроме message есть блок с именем поставщика и его исходным ответом. Там написано: перегрузка, таймаут, контекст или параметр.

Повторите с паузой

Для перегрузки и таймаута хватает повтора через 2–5 секунд. В SDK OpenAI это max_retries: 502 повторяется автоматически, пауза растёт сама.

from openai import OpenAI
client = OpenAI(
    api_key="sk-or-...",
    base_url="адрес OpenRouter из документации",
    max_retries=5,
    timeout=120,
)

Разрешите запасной маршрут

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

response = client.chat.completions.create(
    model="deepseek/deepseek-chat",
    messages=[{"role": "user", "content": "ping"}],
    extra_body={"provider": {"allow_fallbacks": True}},
)

Задайте порядок поставщиков

Если ошибка стабильно у одного поставщика, поставьте другого первым через order. Имена поставщиков видны на странице модели у OpenRouter.

extra_body={"provider": {
    "order": ["Anthropic"],
    "allow_fallbacks": True,
}}

Смените модель

Если 502 идёт у всех поставщиков одной модели, дело в модели: у неё сегодня плохой день. Возьмите соседнюю из того же семейства и вернитесь позже.

/ По инструментам

Где это чинится в разных инструментах

Cursor, Cline, Continue. Ошибка приходит в чат как есть, вместе с текстом поставщика. Повторите запрос; порядок поставщиков в редакторе не настраивается, только в настройках аккаунта OpenRouter.
Python и Node.js SDK. 502 ловится как InternalServerError и повторяется через max_retries. Поля provider передаются через extra_body.
n8n, Make. Включите Retry On Fail с паузой 5 секунд и 3 попытками: этого хватает на большинство перегрузок.
LangChain. Параметры маршрута идут через model_kwargs или extra_body у модели, повторы — with_retry().

/ FAQ

Частые вопросы

Списываются ли деньги за запрос с Provider returned error?

Нет. Запрос не выполнен, кредиты за него не снимаются.

Почему ошибка приходит только на одной модели?

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

Это ошибка OpenRouter или моя?

Ни то ни другое: сломалось у поставщика модели. Ваша сторона — только повтор и выбор маршрута.

/ На kosareva.cloud

Как это выглядит у нас

У нас модели идут через один шлюз, и выбора поставщика в запросе нет: поле provider не используется, маршрут задаём мы сами. Если сбой случился на нашей стороне или у поставщика, ответ приходит как 502 или 503 с телом ошибки, повторы в SDK работают штатно, а за неудачный запрос списания нет. Баланс и расход по ключу видны в кабинете.

/ Дальше

Рядом в справочнике

Ключ, который работает из России

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

Получить ключ