Примечание автора: разбираемся, как определять порядок действий при ошибках API моделей по кодам ответа: когда повторить запрос, когда переключиться на резервную модель, а когда остановиться и исправить конфигурацию. В статье — таблица ошибок, список проверки резервной модели и чек-лист перед запуском.
Если API модели вернул ошибку, сначала определите её тип, а затем решите, что делать. Ошибки 4xx чаще всего связаны с запросом или конфигурацией — повторный запрос их не исправит. При ошибках 5xx, включая 529, и тайм-аутах стоит попробовать ограниченное число повторов; если они не помогли, переключайтесь на резервную модель. Запросы без гарантии идемпотентности нельзя повторять автоматически. Повторный запрос не должен быть действием по умолчанию, а переключение на другую модель решает не все проблемы. Многие инциденты в продакшене происходят не из-за отказа модели, а из-за того, что обработка ошибок превращает небольшой сбой в повторные списания, дубли записей в базе и ограничение запросов по всей цепочке.
Это не перевод справочника кодов ошибок. Статья адресована разработчикам, которые уже подключили API моделей к продакшену или близкой к нему среде. Главное здесь — как не усугубить ситуацию при сбое. В конце у вас будут таблица разбора ошибок, стратегия повторных запросов и переключения на резервную модель, список проверки её возможностей и готовый чек-лист перед запуском. Всё можно свести к одному правилу: при 4xx сначала исправляем причину, при 5xx рассматриваем повтор, а неидемпотентные запросы не повторяем автоматически.
5 категорий ошибок API моделей: сначала классификация, затем повтор или переключение
Сразу к сути: ошибки API моделей можно разделить на пять категорий, и для каждой есть свой стандартный порядок действий. Сначала отнесите код ошибки к одной из них — тогда не запутаетесь с повторами и переключениями.
| Категория ошибки | Типичные коды статуса | Где искать причину | Действие по умолчанию |
|---|---|---|---|
| Ошибка запроса | 400, 404, 409, 422 |
Тело запроса, параметры, ID модели, эндпоинт | Не повторять, исправить запрос |
| Ошибка авторизации | 401, 403 |
API-ключ, заголовки, права доступа, регион или политика | Не повторять, проверить API-ключ и права |
| Квота или ограничение частоты | 402, 429 |
Баланс, число параллельных запросов, частота, квота модели | При 402 остановиться; при 429 проверить тело ошибки, затем применить задержку или переключиться |
| Сбой вышестоящего сервиса | 500, 502, 503, 529 |
Шлюз, вышестоящий сервис, перегрузка | Повторить ограниченное число раз, затем переключиться |
| Тайм-аут или прерывание потока | 408, 504, сетевой тайм-аут, обрыв потока |
Сетевое соединение, длинный вывод, медленный ответ вышестоящего сервиса | Сначала проверить, был ли запрос выполнен и списана ли плата; повторять только идемпотентные запросы |
Главное при разборе 5 категорий ошибок: различать повтор и переключение
Повтор — это отправка запроса ещё раз той же модели и по тому же маршруту. Он помогает справиться с кратковременными сбоями. Переключение — это смена модели или маршрута; оно подходит, когда один из вышестоящих сервисов недоступен в течение длительного времени. Цена у этих действий разная: повтор увеличивает задержку и может привести к повторному списанию, а переключение может повлиять на качество ответа, совместимость с вызовами инструментов и стоимость.
Поэтому порядок действий всегда состоит из трёх шагов: сначала определите категорию ошибки, затем проверьте, идемпотентен ли запрос, и только после этого выберите повтор, переключение или остановку. Пропускать второй шаг особенно опасно: повторное выполнение уже завершённого вызова инструмента может обернуться не просто «лишними расходами».
Почему повтор всех запросов усугубляет ошибки API моделей
Коротко: повторять запрос при любой ошибке кажется надёжным решением, но на практике это увеличивает расходы, усиливает побочные эффекты и усугубляет ограничения частоты запросов. В продакшене последствия такой логики зачастую сложнее диагностировать, чем исходную ошибку.
Первая проблема — двойная оплата. Прерывание потокового ответа не обязательно означает, что запрос завершился неудачно: на стороне поставщика уже могла быть сгенерирована часть токенов, за которую начислена плата. При бездумном повторе получается, что за одну задачу приходится платить дважды. Особенно заметно это при длинных ответах.
Вторая проблема — повторное выполнение действий. В сценариях с агентами один запрос к модели может привести к записи в базу данных, отправке сообщения, созданию задачи и даже оплате. Если при вызове инструмента произошёл тайм-аут, вы не знаете, успел ли он выполниться. Если сразу повторить весь запрос, легко получить два заказа или два письма вместо одного.
Третья проблема — усугубление ограничений частоты запросов. Ошибкой 429 поставщик буквально говорит: «Помедленнее». Если клиент в ответ сразу запускает параллельные повторы, он лишь увеличивает нагрузку. Ещё один распространённый антипаттерн — повторять запросы при всех ошибках 4xx. Например, 401 изначально вызвана неправильно указанным ключом. После нескольких повторов лимит запросов исчерпывается, и в логах появляется множество ошибок 429, которые маскируют настоящую причину.
Таблица ошибок 401, 429, 500 и 529: когда повторять запрос, а когда переключаться
Коротко: в таблице собраны 14 самых распространённых в продакшене кодов состояния. Повторять запрос стоит лишь для некоторых из них, а переключаться — когда уже ясно, что повторные попытки не помогают. Под переключением в таблице понимается переход на резервную модель или маршрут. Точный смысл ошибки зависит от тела ответа и документации провайдера.
| Код состояния | Обычно означает | Повторять запрос? | Переключаться? | Что делать |
|---|---|---|---|---|
400 |
Ошибка формата запроса или параметров | Нет | Нет | Исправить тело запроса, проверить поля и типы |
401 |
Недействительный ключ или ошибка аутентификации | Нет | Нет | Проверить ключ, заголовок Authorization и Base URL |
402 |
Недостаточно средств или исчерпана квота | Нет | При необходимости сменить маршрут | Пополнить баланс или перейти на маршрут с доступной квотой и отправить оповещение |
403 |
Отказ из-за прав доступа, региона или политик | Нет | Нет | Проверить права аккаунта, доступ к модели и региональные ограничения |
404 |
Модель или эндпоинт не найдены | Нет | Нет | Проверить ID модели и путь эндпоинта |
408 |
Время ожидания запроса истекло | Ограниченное число попыток, если операция идемпотентна | Необязательно | Убедиться, что операция не была выполнена, и повторить запрос один раз |
409 |
Конфликт или несогласованность состояния | Нет | Нет | Проверить состояние операции, избегать параллельной записи |
422 |
Ошибка валидации параметров | Нет | Нет | Исправить параметры; ошибка часто связана со схемой структурированного вывода |
429 |
Ограничение частоты, параллельных запросов или квоты | Повторить с задержкой | Можно переключиться, если повторные попытки не помогли | Сначала прочитать тело ошибки и Retry-After |
500 |
Внутренняя ошибка вышестоящего сервиса | Ограниченное число попыток | Переключиться при повторных сбоях | Записать request id и тело ошибки |
502 |
Ошибка шлюза | Ограниченное число попыток | Можно переключиться | Выяснить, проблема в шлюзе или в вышестоящем сервисе |
503 |
Сервис недоступен | Ограниченное число попыток | Можно переключиться | Учитывать Retry-After, при необходимости перейти в ограниченный режим |
504 |
Истекло время ожидания шлюза | Только если операция идемпотентна | Можно переключиться | Сначала проверить, не была ли задача уже выполнена |
529 |
Вышестоящий сервис перегружен | Ограниченное число попыток | Можно переключиться | Повторять с увеличивающейся и случайной задержкой; если перегрузка не проходит, переключиться |
429 — не всегда ограничение частоты: сначала прочитайте тело ошибки
Код 429 особенно легко неверно истолковать. Он может означать ограничение частоты запросов, превышение числа параллельных запросов или исчерпание квоты модели; в отдельных случаях он также связан с балансом. При ограничении частоты обычно достаточно подождать несколько секунд перед повтором. Но если квота исчерпана, повторные попытки не помогут. А переход сразу на самую дорогую модель лишь удвоит расходы, не решив проблему.
При ошибке 429 действуйте так:
- Проверьте заголовок ответа
Retry-Afterи, если он есть, подождите указанное время. - Прочитайте поле с типом ошибки в теле ответа, чтобы различить rate limit, concurrency и quota.
- При ограничении частоты или числа параллельных запросов повторите запрос 1–2 раза с задержкой и уменьшите число параллельных запросов на своей стороне.
- Если проблема в квоте, прекратите повторы, отправьте оповещение и переключитесь на маршрут с доступной квотой.
С 500 подход похожий. Этот код не обязательно означает, что проблема в самой модели: причиной может быть как шлюз, так и вышестоящий сервис. Сначала сохраните request id и краткое содержимое ошибки — они пригодятся для диагностики и сверки.
Стратегия повторных попыток при ошибках API модели: число попыток, задержка, Retry-After и идемпотентность
Главное: повторяйте запросы только при временных ошибках, ограничьте число повторных попыток одной или двумя, обязательно используйте экспоненциальную задержку со случайным разбросом и автоматически повторяйте только идемпотентные запросы. Если хотя бы одно из этих четырёх условий не выполнено, не включайте автоматический повтор.
| Параметр | Рекомендуемое значение | Пояснение |
|---|---|---|
| Ошибки, допускающие повтор | 429、500、502、503、504、529、сетевой тайм-аут |
Среди ошибок 4xx исключение составляют только 408 и 429 |
| Максимальное число повторных попыток | 1–2 | После этого переключайтесь на другой вариант или отправляйте предупреждение, не продолжайте безрезультатные попытки |
| Интервал между попытками | 1s、2s、4s с экспоненциальным ростом | Каждый раз добавляйте случайный разброс, чтобы несколько экземпляров не повторяли запрос одновременно |
| Retry-After | При наличии соблюдайте в первую очередь | Имеет приоритет над локальным алгоритмом задержки |
| Условие идемпотентности | Обязательно | Операции записи, вызовы инструментов, отправку сообщений и платежи по умолчанию автоматически не повторяют |
Как реализовать стратегию повторных попыток
- Создайте функцию классификации ошибок. Она принимает код состояния и тело ошибки, а возвращает одну из пяти категорий. Остальная логика должна опираться на результат классификации, а не проверять числовые коды по всему приложению.
- Пометьте запросы по признаку идемпотентности. Обычную генерацию текста, суммаризацию и перевод обычно можно считать идемпотентными. Если запрос запускает инструмент или приводит к внешней операции записи, пометьте его как неидемпотентный.
- Перед повтором неидемпотентного запроса проверьте состояние. Если при вызове инструмента произошёл тайм-аут, сначала проверьте состояние задачи или базы данных. Повторяйте запрос, только убедившись, что операция не была выполнена. При необходимости используйте ключ идемпотентности на стороне приложения для исключения дубликатов.
- Ограничьте общее время. Установите предел времени для всех повторных попыток одного запроса. Иначе запрос пользователя уже завершится по тайм-ауту, а сервер продолжит попытки в фоновом режиме.
- Записывайте каждую попытку. Как минимум сохраняйте request id, ID модели, код состояния, класс ошибки, задержку, расход токенов и число повторных попыток.
Последний шаг часто пропускают, но без него сложно сверять расходы и искать причины ошибок. Если вы подключаетесь через APIYI apiyi.com, в консоли можно просмотреть расход и журналы вызовов по ключу. Сопоставив локально записанный request id с ошибкой на платформе, вы сможете определить, где произошёл сбой: на шлюзе, у вышестоящего провайдера или в теле вашего запроса.
Обрывы потока обрабатывайте отдельно. Если потоковый запрос прервался, сначала проверьте, сколько токенов уже получено и можно ли использовать имеющийся текст. Затем решите, продолжить генерацию, отбросить результат или повторить запрос. Прежде чем повторять задачу с длинным ответом, учтите: предыдущая генерация уже могла быть тарифицирована.
🎯 Совет по устранению ошибок: столкнувшись с ошибкой вроде
500или529, источник которой сложно определить, сначала сохраните исходное тело ошибки и request id. Затем проверьте расход и журналы за тот же период в консоли APIYI apiyi.com. Не делайте выводов только по коду состояния.
Стратегия перехода на резервную модель: уровни возможностей, сопоставление моделей и проверка совместимости
Главное: переключаться на резервную модель можно только после того, как вы заранее убедились, что она справляется с теми же задачами. Если впервые проверить резервный сценарий уже во время сбоя, велика вероятность получить ещё один сбой.
Для начала разделите модели на уровни: флагманские, универсальные и лёгкие. Для каждого типа задач назначьте основную и резервную модель того же или соседнего уровня. Не стоит перенаправлять все запросы на самую дорогую модель: один сбой у поставщика — и расходы могут выйти из-под контроля. К тому же для многих простых задач переход на флагманскую модель не даст никакой пользы.
| Возможность | Основная модель | Резервная модель | Совместимость | Что проверить перед переключением |
|---|---|---|---|---|
| Контекстное окно | Указать фактический предел | Указать фактический предел | Требует проверки | Убедиться, что самый длинный реальный ввод помещается в окно; иначе заранее подготовить стратегию усечения |
| Вызов инструментов | Схема инструментов, параллельные вызовы | То же | Требует проверки | Проверить формат возврата ID вызова и структуру параметров |
| Структурированный вывод | JSON schema или строгий JSON | То же | Требует проверки | Проверить процент успешных ответов с одной и той же схемой, чтобы избежать 422 |
| Мультимодальный ввод | Изображения, аудио, видео | То же | Требует проверки | Проверить форматы ввода и ограничения на размер |
| Параметры reasoning | Уровень рассуждений или поле для настройки обдумывания | То же | Требует проверки | При переключении удалить неподдерживаемые параметры или преобразовать их |
| Цена и лимиты запросов | Согласно консоли | Согласно консоли | Требует проверки | Оценить расходы после переключения и убедиться, что лимитов достаточно |
| Регионы и нормативные требования | Допустимый диапазон | Допустимый диапазон | Требует проверки | Убедиться, что резервный маршрут соответствует региональным и нормативным требованиям бизнеса |
Рекомендуется заполнить такую таблицу для каждого типа задач. В колонку «Совместимость» заносите только результаты проверки, а не предположения. Особенно часто проблемы возникают с параметрами reasoning: поле уровня рассуждений, которое поддерживает основная модель, при передаче резервной может сразу вызвать ошибку 400 или 422. В логике переключения нужен слой адаптации параметров — не передавайте их без изменений.
Сопоставление моделей: сверяйте ID моделей с консолью
Одна из самых распространённых ошибок при переключении — неверный ID модели, из-за которого возвращается 404. Рекомендуется вести таблицу соответствия между логическими именами и фактическими ID моделей, а в коде приложения использовать только логические имена. При вызове через APIYI apiyi.com сверяйте точные ID моделей, их доступность и цены с консолью и документацией. Для подключения используйте единый base_url: https://api.apiyi.com/v1. После изменения таблицы соответствия выполните канареечный запрос и только затем публикуйте изменения.
Проверка резервной модели и мультимодельный шлюз: канареечные запросы, логи и автоматическое переключение
Главное: перед запуском резервную модель нужно проверить на реальных задачах, а после переключения — проверить её ответы, а не только убедиться, что статус-код равен 200. Мультимодельный шлюз упрощает переключение, но не заменяет проверку качества.
Проверка резервной модели в три шага
- Канареечные запросы. Выберите несколько реальных бизнес-задач и отправьте их основной и резервной моделям с одинаковым промптом, инструментами и входными данными.
- Сравнение на одинаковых задачах. Сравните долю успешно выполненных задач, задержку, время до первого токена, стоимость токенов и частоту ошибок. Для задач с вызовом инструментов также проверьте совместимость ID вызовов, структуры параметров и возвращаемых данных.
- Проверка после переключения. После реального переключения автоматически проверьте ответы: например, можно ли разобрать JSON, заполнены ли обязательные поля, корректны ли параметры инструментов. Запишите причину переключения и результаты проверки.
Сценарий переключения на резервную модель нужно регулярно отрабатывать. Например, раз в неделю можно вручную направлять на неё небольшую часть трафика, чтобы убедиться, что вся цепочка по-прежнему работает и зависимости, параметры или ID моделей незаметно не устарели.
В логи рекомендуется включать как минимум:
- ID запроса, ID модели, эндпоинт, статус-код, класс ошибки, краткое содержимое ошибки
- Задержку, время до первого токена, общее время выполнения, число повторных попыток, модель, на которую произошло переключение
- Входные и выходные токены, попадание в кэш, расчётную стоимость
- Имя вызванного инструмента, ID вызова, результат выполнения
- Причину переключения и результат проверки после него
Роль мультимодельного шлюза в обеспечении отказоустойчивости
При самостоятельном подключении к нескольким поставщикам для обеспечения отказоустойчивости придётся поддерживать несколько наборов ключей, SDK и форматов ошибок. С агрегирующим шлюзом, таким как APIYI apiyi.com, одного ключа достаточно для вызова популярных моделей OpenAI, Claude, Gemini, DeepSeek, Qwen и других. Интерфейс совместим со стандартом OpenAI, а также поддерживает нативные форматы Claude и Gemini. Основную и резервную модели можно подключить в одном коде: при переключении меняется ID модели, а не вся цепочка интеграции.
Платформа также предлагает развёртывание на нескольких узлах, интеллектуальную маршрутизацию, автоматическое переключение на резерв и балансировку нагрузки. Это помогает сгладить часть перебоев на стороне поставщиков. Однако автоматическое переключение на уровне шлюза не заменяет проверки на уровне приложения: проверку идемпотентности, дедупликацию вызовов инструментов и проверку результатов по-прежнему нужно реализовать в своём коде. Надёжное разделение ответственности выглядит так: шлюз отвечает за доступность соединений и узлов, а приложение — за корректность выполнения задач.
💡 Совет по обеспечению отказоустойчивости: при настройке основной и резервной моделей можно сначала запустить один и тот же набор канареечных задач для обеих моделей в APIYI apiyi.com, используя один ключ. Затем внесите проверенные комбинации в таблицу сопоставления моделей. Новые пользователи могут провести проверку в пределах бесплатного тестового лимита.
Частые вопросы об ошибках API моделей
Главное: эти пять вопросов охватывают самые спорные ситуации в продакшене. Во всех случаях принцип один: сначала разобраться, потом действовать.
Q1: Стоит ли повторять запрос при ошибке 401?
Нет. `401` означает ошибку аутентификации. Повторные запросы лишь увеличат нагрузку и могут привести к ошибке `429`. Проверьте, действителен ли ключ, правильно ли указан заголовок `Authorization` и относятся ли Base URL и ключ к одной платформе. Если используете APIYI apiyi.com, проверьте статус ключа в консоли.
Q2: Нужно ли сразу менять модель при ошибке 429?
Не стоит. Сначала изучите тело ошибки и заголовок `Retry-After`: если сработало ограничение частоты или числа параллельных запросов, обычно достаточно повторить запрос 1–2 раза с увеличивающейся задержкой. Переключаться на другой маршрут стоит, когда исчерпана квота. При переключении выбирайте резервную модель того же уровня, а не самую дорогую.
Q3: Стоит ли повторять запрос, если потоковая выдача прервалась?
Не спешите. Прерывание потока не обязательно означает, что запрос завершился неудачей: часть содержимого могла быть уже сгенерирована и оплачена. Сначала проверьте количество полученных токенов и пригодность содержимого: если его можно использовать, сохраните или продолжите генерацию; если нет, а запрос идемпотентен, повторите его 1 раз. Фактическое списание проверяйте по статистике использования в консоли.
Q4: Что делать, если инструмент выполняется повторно?
Надёжное решение — обеспечить идемпотентность на уровне инструмента: использовать бизнес-ключ идемпотентности или ID задачи для дедупликации, чтобы каждый ID выполнялся только один раз. Если вызов инструмента завершился по тайм-ауту, сначала проверьте статус задачи и повторяйте вызов только после того, как убедитесь, что она не была выполнена. Если дублирование уже произошло, найдите записи в логах по ID вызова и компенсируйте или отмените лишние операции.
Q5: Что делать, если после переключения на резервную модель вернулся код 200, но результат неверный?
Код 200 говорит лишь об успешном выполнении запроса, но не задачи. Автоматически проверяйте результат: например, структуру JSON, обязательные поля и допустимость параметров инструмента. Неудачную проверку нужно учитывать в доле ошибок и запускать оповещение или ручную проверку. Если какая-то резервная комбинация часто не проходит проверку, удалите её из таблицы сопоставления и заново проведите канареечное тестирование.
Чек-лист перед запуском и итоги: когда повторять запрос, переключаться или остановиться
Вывод: перед запуском надёжнее пройтись по каждому пункту чек-листа, чем дописывать логику уже после сбоя. Запомните правило: при 4xx сначала исправляем ошибку, при 5xx рассматриваем повтор, а неидемпотентные запросы сначала останавливаем.
| № | Что проверить | Критерий готовности |
|---|---|---|
| 1 | Сначала определить тип ошибки | Любой код состояния можно отнести к одной из пяти категорий; неизвестные ошибки по умолчанию не повторяются |
| 2 | Не повторять 4xx автоматически | При 400, 401, 402, 403, 404, 409, 422 сразу отправляется уведомление или исправляется ошибка |
| 3 | Затем решить, повторять запрос или переключаться | Повторяются только запросы с временными ошибками, не более 1–2 раз, с увеличением задержки и случайным разбросом |
| 4 | Учитывать Retry-After | Если заголовок присутствует в ответе, время ожидания в первую очередь определяется по нему |
| 5 | Проверить идемпотентность | Вызовы инструментов, операции записи, отправка сообщений и платежи по умолчанию останавливаются; дальнейшее решение принимается после проверки состояния |
| 6 | Обработать прерывание потока | Сначала проверяются уже полученные токены и расходы; запрос не повторяется вслепую |
| 7 | Проверить резервную модель | Таблица возможностей заполнена и проверена для каждого типа задач |
| 8 | Проверить сопоставление моделей | Сопоставление логических имён с ID моделей соответствует настройкам в консоли |
| 9 | Проверить результат | После переключения проверяются структура и поля ответа, а не только код 200 |
| 10 | Проверить логи и провести учения | Все ключевые поля присутствуют, сценарий перехода на резерв регулярно отрабатывается |
Обработка ошибок API моделей: главное
- Когда повторять запрос: при
429,500,502,503,529и тайм-аутах идемпотентных запросов — ограниченное число раз и с увеличением задержки. - Когда переключаться: если повторные попытки не помогли, вышестоящий сервис остаётся недоступным или квота исчерпана, а резервная модель уже проверена.
- Когда остановиться: при ошибках конфигурации с кодами 4xx, например
401, а также при неидемпотентных запросах с неизвестным состоянием. - Переключение не означает успеха: даже после ответа 200 от резервной модели нужно проверить результат.
- Разделение задач между шлюзом и приложением: шлюз отвечает за доступность каналов, а бизнес-код — за правильность выполнения задачи.
Качество обработки ошибок определяется не тем, насколько активно система повторяет запросы, а тем, принимает ли она верное решение при каждом сбое. Для начала стоит настроить классификацию ошибок, метки идемпотентности и поля логов, а затем постепенно добавлять резервные модели. В качестве резервного канала можно рассмотреть APIYI apiyi.com: один ключ даёт доступ к моделям нескольких ведущих поставщиков, что позволяет проверять основную и резервную модели и переключаться между ними с помощью одной кодовой базы. Актуальные цены и доступность уточняйте в консоли и документации.
📚 Справочные материалы
- Центр документации APIYI: способы подключения, список моделей и информация о тарифах
- Ссылка:
docs.apiyi.com -
Примечание: актуальные ID моделей, цены и доступность указаны в документации и консоли
-
Описание HTTP-кодов состояния: значения стандартных заголовков ответа, включая
Retry-After - Ссылка:
developer.mozilla.org/docs/Web/HTTP/Status - Примечание: помогает разобраться в общем значении кодов 4xx и 5xx; конкретный смысл ошибки зависит от содержимого ответа платформы модели
Автор: техническая команда APIYI
Технические вопросы: свяжитесь с нами через главную страницу сайта APIYI apiyi.com. Дополнительные материалы по подключению доступны в центре документации docs.apiyi.com.
