Ошибки ИИ-API: 401, 403, 429 и 5xx
Диагностика ошибок ИИ-API: аутентификация, политики доступа, лимиты запросов, отмена клиентом и сбои поставщика — и когда повторять запрос безопасно.

Ошибки ИИ-API проще всего диагностировать, если считать код ответа отправной точкой расследования, а не полной причиной. Прежде чем повторять запрос, сохраните ID запроса, время, эндпоинт, модель, название API-ключа, выбранную группу, тело ответа и временные метрики.
Цель — определить, на каком уровне запрос был отклонён или прерван: клиент, аутентификация, политика доступа, проверка протокола, маршрутизация, бэкенд модели или соединение на стороне клиента (downstream).
Что обычно означают распространённые коды ответа
| Код | Первичная интерпретация | Первое действие |
|---|---|---|
| 400 | Неверная структура запроса, поле или нарушение контракта протокола | Сравните тело запроса с требованиями выбранного эндпоинта; не повторяйте без изменений |
| 401 | Учётные данные отсутствуют, имеют неверный формат, отключены, просрочены или недействительны | Проверьте заголовок Authorization и текущий ключ |
| 403 | Аутентификация пройдена, но запрос заблокирован политикой аккаунта, модели, группы, IP или другими правилами | Проверьте ограничения ключа и доступ к модели и группе, прежде чем проверять каналы |
| 404 | Неверный путь эндпоинта или недоступный ID модели | Проверьте базовый URL, путь и список моделей, доступных ключу |
| 429 | Лимит запросов, кредитов или доступных маршрутов | Проверьте кредиты и лимиты группы; используйте ограниченный backoff или настроенные резервные группы |
| 499 | Клиент отключился или отменил запрос до завершения | Проверьте дедлайны клиента, отмены, прокси и время до первого вывода |
| 500 | Сбой внутренней обработки или адаптера | Сохраните ID запроса; повторяйте, только если операция безопасна |
| 502/503 | Некорректный ответ поставщика, недоступный маршрут или временная нехватка мощностей | Проверьте данные о маршруте и используйте ограниченное переключение на резервную группу или повтор |
| 504 | Истёк бюджет времени шлюза или поставщика | Сравните время до первого вывода и общее время с дедлайнами клиента |
Эти интерпретации — отправные точки для диагностики. Фактическую причину конкретного вызова определяют тело ошибки и запись запроса.
Диагностируйте 401, прежде чем менять модель
Ошибка 401 обычно возникает ещё до полезной маршрутизации модели. Проверьте, что:
- заголовок имеет вид Authorization: Bearer ...;
- приложение не добавило кавычки, пробелы или значение-заполнитель;
- ключ включён и срок его действия не истёк;
- запрос отправляется на нужный хост Modelflare;
- менеджер секретов или развёртывание не сохранили старый ключ, который уже заменён при ротации.
Не вставляйте полный ключ в журналы и сообщения в поддержку. Если ключ мог быть раскрыт, воспроизведите проблему с отдельным тестовым ключом, а скомпрометированный отзовите.
Диагностируйте 403 прежде всего как отказ политики доступа
Ошибка 403 не означает автоматически, что запрос отклонил поставщик. Аутентификация может пройти успешно, а в доступе может быть отказано ещё до выбора канала, потому что:
- ключ ограничивает запрошенную модель;
- белый список IP ключа не включает IP-адрес клиента, который видит шлюз;
- аккаунт не может использовать выбранную группу моделей;
- пользователь или ключ отключены по правилам;
- запрошенная функция не разрешена для этого маршрута.
Запросите /v1/models с тем же ключом, проверьте его группу и ограничения моделей и сравните точный код ошибки. Если канал не был выбран, смена канала поставщика не исправит более раннее решение политики.
Диагностируйте 429, не устраивая шквал повторов
429 — это сигнал о нехватке мощностей или о срабатывании политики, а не указание немедленно повторять запрос в плотном цикле. Определите, к чему относится лимит: к кредитам ключа, аккаунту, группе моделей или выбранному маршруту.
Для лимитов запросов, после которых повтор допустим:
- соблюдайте Retry-After, если этот заголовок есть;
- используйте экспоненциальную задержку (backoff) со случайным разбросом (jitter);
- ограничьте число попыток и общее затраченное время;
- держите параллелизм приложения в известных пределах;
- используйте упорядоченные резервные группы, только если они сохраняют запрошенные модель и протокол.
Дополнительные API-ключи не обязательно позволяют обойти лимит запросов на уровне аккаунта или группы.
Диагностируйте 499, начиная с вызывающей стороны
Modelflare может записать 499, если соединение на стороне клиента завершилось до окончания ответа. Начните с вызывающей стороны:
- Сработал ли сигнал отмены (abort)?
- Не достиг ли клиент, балансировщик нагрузки, CDN или обратный прокси тайм-аута простоя или общего тайм-аута?
- Не закрыл ли пользователь страницу и не остановил ли агента?
- Не выдал ли поток событие инструмента без видимого текста?
- Сколько времени прошло до первого полезного вывода?
Одна запись 499 не доказывает сбой канала. Прежде чем менять политику маршрутизации, сравните другие запросы за тот же период с той же моделью и группой.
Разделяйте ошибки 5xx по уровням
Для ошибок 5xx сохраняйте исходный статус и подробности ошибки, а не превращайте на клиенте любой сбой в обобщённую ошибку 500.
- Ошибка 500 при проверке или в адаптере может быть детерминированной и повторится, если ничего не изменить.
- Ошибка 502 может указывать на некорректный или неполный ответ поставщика.
- Ошибка 503 может означать, что подходящего маршрута нет или сервис временно недоступен.
- Ошибка 504 означает, что истёк бюджет времени, но ответственный уровень ещё нужно определить.
Чтобы отличить единичный неудачный ответ от устойчивой проблемы маршрута, используйте временные метрики запроса, выбранную группу, данные о канале, доступные поддержке, и соседние запросы.
Решите, стоит ли повторять запрос
| Класс сбоя | Решение о повторе по умолчанию |
|---|---|
| Недопустимое тело запроса или неподдерживаемый протокол | Исправьте запрос; не повторяйте без изменений |
| Недействительный ключ или отказ в доступе | Исправьте учётные данные или политику; не повторяйте без изменений |
| Кредиты исчерпаны | Осознанно увеличьте или перераспределите кредиты; не повторяйте в цикле |
| Лимит запросов | Повторяйте с ограниченным backoff, если это допустимо |
| Временные 502/503/504 | Повторяйте идемпотентные операции со строгим лимитом попыток |
| Отмена клиентом | Повторяйте, только если результат ещё нужен пользователю и дубли безопасны |
| Побочные эффекты инструментов или записи данных | Прежде чем повторять, обеспечьте идемпотентность на уровне приложения |
Повторы создают новую работу и могут повлечь новые расходы. Фиксируйте каждую попытку и не скрывайте исходный сбой за последующим успехом.
Какие данные безопасно собирать
Для поддержки или разбора инцидента зафиксируйте:
- ID запроса и время в UTC;
- эндпоинт и режим потоковой передачи;
- запрошенную модель и выбранную группу;
- HTTP-статус и структурированный код ошибки;
- общее время и время до первого полезного вывода;
- отменила ли запрос вызывающая сторона;
- обезличенное описание используемых в запросе функций, например инструментов или ввода изображений.
Не включайте полный API-ключ, промпт, содержимое ответа, необработанное тело запроса, адрес электронной почты или IP-адрес в открытом виде, если этого прямо не требует утверждённый защищённый процесс.
Определив уровень сбоя, используйте статью Надёжная маршрутизация ИИ-API для проектирования резервных групп и руководство по потоковой передаче — для сбоев, связанных с событиями и тайм-аутами.
Частые вопросы
Доказывает ли 403, что провайдер недоступен?
Нет. Ошибку 403 могут вернуть политики аккаунта, ключа, модели, группы, IP или функции ещё до выбора маршрута поставщика. Сначала проверьте запись запроса и код ошибки.
Является ли 499 стандартной ошибкой модели поставщика?
Нет. В записях запросов Modelflare это отмена на стороне клиента, зафиксированная до завершения ответа. Прежде чем считать её сбоем модели, проверьте дедлайны вызывающей стороны и прокси.
Нужно ли повторять каждый ответ 5xx?
Нет. Повторяйте только операции, которые безопасно выполнить повторно, ограничивайте число попыток и общее время и сохраняйте первую ошибку. Детерминированные проблемы адаптера или запроса от повторов не исчезнут.