Ошибки ИИ-API: 401, 403, 429 и 5xx
Пошагово диагностируйте аутентификацию, политики доступа, лимиты, отмены клиента и ошибки провайдера; определяйте безопасный повтор.
HTTP-статус начинает диагностику ИИ-API, но не описывает всю причину. До повтора сохраните ID запроса, время UTC, endpoint, модель, имя ключа, группу, структурированную ошибку и тайминги. Затем определите слой: клиент, аутентификация, политика, протокол, маршрут, backend или соединение downstream.
Первичная трактовка
| Статус | Первое значение | Первое действие |
|---|---|---|
| 400 | Неверный payload или контракт | Исправить, не повторять без изменений |
| 401 | Ключ отсутствует, неверен или просрочен | Проверить Authorization и текущий ключ |
| 403 | Политика аккаунта, модели, группы или IP | Проверить ограничения до каналов |
| 404 | Неверный путь или ID модели | Проверить Base URL и /v1/models |
| 429 | Лимит квоты, частоты или маршрута | Найти уровень и ограниченно отступить |
| 499 | Клиент отменил до завершения | Проверить deadline, Abort, proxy и первый результат |
| 502/503/504 | Upstream, доступность или время | Сохранить доказательства, ограниченно повторить |
Диагностика по слоям
401 обычно возникает до маршрутизации. Проверьте Authorization: Bearer ..., состояние ключа, host и старые секреты в deployment. Не помещайте полный ключ в логи и обращения.
403 не доказывает отказ поставщика. Ограничение моделей, IP allowlist, доступ к группе или политика аккаунта могут сработать до выбора канала. Вызовите /v1/models с тем же ключом и изучите точный код.
При 429 выясните, что ограничено: ключ, аккаунт, группа или маршрут. Соблюдайте Retry-After, используйте экспоненциальный backoff с jitter, ограничивайте число, время и concurrency. Дополнительные ключи не обязательно обходят лимит аккаунта.
499 фиксирует завершение downstream-соединения. Начните с Abort, браузера, CDN, балансировщика и proxy; сравните первый полезный результат. Одна запись не доказывает сбой канала.
Решение о повторе
- Неверный запрос, ключ или доступ: исправить, не повторять прежнее.
- Rate limit: ограниченный backoff только когда разрешено.
- Временные 502, 503 или 504: только идемпотентная работа с жёстким бюджетом.
- Отмена клиента: убедиться, что результат ещё нужен и эффекты не дублируются.
- Инструменты или запись: сначала обеспечить идемпотентность приложения.
Каждая попытка создаёт работу и стоимость. Безопасно передавать ID, время, endpoint, streaming, модель, группу, статус, код и тайминги; не полный ключ, prompt, ответ, body, email или открытый IP. Далее используйте маршрутизацию и streaming-гайд.
Проверки по уровням
Для 401
Проверьте Authorization: Bearer ..., лишние кавычки и пробелы, состояние ключа и старые секреты в deployment. Такая ошибка обычно возникает до маршрутизации модели.
Для 403
Тем же ключом проверьте разрешённые модели, список IP, доступ к группе и политику аккаунта. Если канал ещё не выбран, смена поставщика не исправит более ранний отказ.
Для 429
Определите, ограничены ли ключ, аккаунт, группа или маршрут. Учитывайте Retry-After, применяйте экспоненциальную задержку со случайным разбросом и ограничивайте число попыток, общее время и параллелизм.
Для 499
Начните с клиента: сигнал отмены, закрытая вкладка, CDN, балансировщик и лимиты прокси. Сопоставьте отмену с первым полезным выводом; отдельный 499 не доказывает сбой канала.
Различать ошибки 5xx
500 может означать детерминированную ошибку адаптера, 502 — неверный или неполный upstream-ответ, 503 — временное отсутствие маршрута, а 504 — исчерпанный бюджет времени. Сохраняйте исходный статус и повторяйте только безопасные операции со строгим лимитом.
Безопасные данные для диагностики
- ID запроса и время UTC;
- endpoint и потоковый режим;
- запрошенная модель и выбранная группа;
- HTTP-статус и структурированный код ошибки;
- общее время и время до первого полезного вывода;
- признак отмены клиентом;
- очищенное описание функций, например инструментов или изображений.
Не включайте полный ключ, промпт, ответ, исходное тело, адрес почты или открытый IP вне явно утверждённого безопасного процесса.
Частые вопросы
Доказывает ли 403 недоступность поставщика?
Нет. Аккаунт, ключ, модель, группа, IP или функциональная политика могут отклонить запрос до выбора поставщика.
Является ли 499 обычной ошибкой upstream-модели?
Нет. В записях Modelflare это downstream-отмена, замеченная до завершения ответа.
Нужно ли повторять любой 5xx?
Нет. Повторяйте только безопасную работу, ограничивайте число попыток и общее время и сохраняйте первую ошибку.