Ошибки ИИ-API: 401, 403, 429 и 5xx
Диагностируйте аутентификацию, политики, лимиты, отмены и upstream по слоям и безопасно решайте вопрос повторов.
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-гайд.