Ошибки ИИ-API: 401, 403, 429 и 5xx

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

Ошибки ИИ-API: 401, 403, 429 и 5xx

Ошибки ИИ-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 — это сигнал о нехватке мощностей или о срабатывании политики, а не указание немедленно повторять запрос в плотном цикле. Определите, к чему относится лимит: к кредитам ключа, аккаунту, группе моделей или выбранному маршруту.

Для лимитов запросов, после которых повтор допустим:

  1. соблюдайте Retry-After, если этот заголовок есть;
  2. используйте экспоненциальную задержку (backoff) со случайным разбросом (jitter);
  3. ограничьте число попыток и общее затраченное время;
  4. держите параллелизм приложения в известных пределах;
  5. используйте упорядоченные резервные группы, только если они сохраняют запрошенные модель и протокол.

Дополнительные 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?

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