Ошибки API нейросетей: 401, 429, 500 и остальные

Ошибки API делятся на две группы, и обращаться с ними нужно по-разному. Класс 4xx — это про ваш запрос: неверный ключ, закрытый доступ, слишком частые обращения; повторять их автоматически бессмысленно, кроме 429. Класс 5xx — про сторону сервиса, и вот их повторять нужно, с паузой, которая растёт с каждой попыткой. Отдельная группа — успешный код с бесполезным содержимым: пустой ответ, обрыв по лимиту, отказ фильтра.

Ниже — таблица кодов с расшифровкой, разбор каждой группы и правила повторов, которые не превращают сбой в счёт.

Таблица кодов

Класс 4xx: проблема в запросе

Общее правило: эти ошибки не проходят сами. Повтор ничего не чинит, а на платном маршруте ещё и стоит денег, если запрос успел дойти до модели.

400 почти всегда означает опечатку в структуре тела: пропущенное поле, строка вместо числа, лишняя запятая. Текст ошибки обычно называет проблемное поле — читать его стоит целиком, а не по первому слову.

401 — механическая ошибка в девяти случаях из десяти. Ключ скопировали вместе с переносом строки, забыли слово Bearer, подставили ключ другого проекта.

403 отличается от 401 принципиально: сервис вас узнал, но доступ к запрошенному закрыт. Причины разные — у ключа нет прав на эту модель, позиция в каталоге в статусе проверки, аккаунт не прошёл условие доступа.

413 и 422 приходят от разных вещей, но чинятся похоже: уменьшить вход и убрать конфликтующие параметры. Например, строгий формат ответа и свободный текст в одном запросе несовместимы — про это подробно в статье JSON от нейросети.

429: единственная ошибка 4xx, которую повторяют

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

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

Класс 5xx: проблема на той стороне

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

Первая: у повторов должен быть предел. Три-четыре попытки, дальше — отказ с понятным сообщением пользователю. Бесконечный цикл ретраев на сбое сервиса превращает инцидент в счёт.

Вторая: если запрос не идемпотентен, слепой повтор может выполнить действие дважды. Для генерации текста это обычно безобидно, для запроса, который что-то меняет в вашей системе, — нет.

Устойчивая схема выглядит так: повторить на том же маршруте, при повторной неудаче уйти на запасную модель, и только потом отдавать ошибку наверх. Как это устроить — в статье отказы маршрута и fallback.

Успешный код и бесполезный ответ

Самая коварная группа: код 200, а работать не с чем.

Пустой ответ. Модель вернула нулевое содержимое. Чаще всего это срабатывание фильтра или неудачная комбинация параметров.

Обрыв на середине. Генерация упёрлась в лимит выходных токенов. В ответе это видно по причине остановки: она говорит, что модель не закончила сама.

Отказ отвечать. Модель ответила текстом вместо результата: «не могу помочь с этим запросом». Формально это успех, фактически — нет. Разбор причин — в статье нейросеть отказывается отвечать.

Выдуманный факт. Худший случай: ответ правильной формы и с неверным содержимым. Ловится не кодом, а проверкой — про это в статье галлюцинации нейросети.

Практический вывод: проверять нужно не только код ответа, но и причину остановки, и непустоту содержимого, и соответствие ожидаемому формату.

Зависания и таймауты

Отдельная категория, у которой часто нет кода вообще: запрос ушёл и не вернулся.

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

Два решения. Увеличить таймаут до разумного значения с запасом на худший случай. Или включить потоковую передачу: ответ приходит частями, первый токен виден сразу, и соединение не выглядит мёртвым. Когда поток нужен, а когда мешает, разобрано в статье потоковая передача: когда нужна.

Как отличить свою поломку от чужой

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

Шаг первый — список моделей. Запрос к перечню позиций не тратит токены и не зависит от вашей логики. Если он проходит, живы и сеть, и ключ, и сервис, а проблема в конкретном запросе.

Шаг второй — минимальный запрос. Та же модель, одно короткое сообщение, никаких инструментов и параметров формата. Если минимальный проходит, а рабочий нет, дело в теле запроса: длина, параметры, формат.

Шаг третий — другая модель. Если минимальный запрос не проходит на одной позиции и проходит на другой, значит, проблема в позиции, а не у вас. Именно для этого случая и нужна заранее настроенная запасная модель.

Эти три шага занимают минуту и заменяют получасовое чтение логов вслепую.

Чего не стоит делать в обработчике

Три антипаттерна, которые встречаются чаще остальных.

Ловить всё подряд одним блоком и молчать. Ошибка, проглоченная без записи в журнал, превращается в загадочное «иногда не работает» через неделю.

Повторять запрос без паузы. Три мгновенных повтора на 429 — это не защита, а утроенная нагрузка, которая продлевает ограничение.

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

Что записать в свой код один раз

Короткий чек-лист обработчика, который закрывает девяносто процентов случаев.

1. Различайте 4xx и 5xx. Первые логируются и отдаются наверх, вторые повторяются.
2. Пауза растёт. Удвоение плюс случайный разброс.
3. У повторов есть предел. Три-четыре попытки и отказ.
4. Проверяйте причину остановки, а не только код ответа.
5. Логируйте идентификатор запроса. Без него разбор инцидента превращается в гадание.

Чего мы не утверждаем

Мы не описываем здесь коды конкретных вендоров построчно: формулировки в теле ошибки у каждого свои и меняются от релиза к релизу.

Мы не утверждаем, что повтор на 5xx безопасен всегда: для запросов, меняющих состояние вашей системы, нужна защита от двойного выполнения.

Мы не даём универсального значения таймаута: оно зависит от модели, длины ответа и того, включён ли поток.

Что нужно, чтобы проверить у себя

Ключ заводится за минуту на keydealer.ru/login — почта и пароль, без документов и без зарубежной карты. Оплата российской картой в рублях.

Самая дешёвая проверка ключа — запрос списка моделей: он не тратит токены и сразу отличает 401 от 403.

Что держать в голове

Класс 4xx повторять бессмысленно, кроме 429; класс 5xx повторять нужно, но с растущей паузой и пределом.

Успешный код не означает полезный ответ: проверяйте причину остановки и непустоту содержимого.

Зависание чаще всего лечится не ретраем, а таймаутом или потоком. Как мы проверяем факты и почему у каждой цифры стоит дата — на странице о проекте. Завести ключ: keydealer.ru/login.