Таксономия ошибок LLM-шлюза — это разница между контролируемым инцидентом и дорогостоящим шквалом повторных попыток. Шлюз не должен рассматривать каждый неудачный вызов модели как один и тот же тип ошибки провайдера. Недействительные учетные данные, исчерпанная квота, перегрузка провайдера, некорректные запросы, отказы по соображениям безопасности, тайм-ауты и отмены со стороны клиента — все это требует разных путей восстановления.
Распространенная ошибка — отправлять каждый сбой в один и тот же цикл повторных попыток и резервных переключений. Это может скрыть отозванный ключ, исчерпать лимит расходов, направить небезопасный контент другому провайдеру или дублировать работу после того, как потоковая передача ответа уже началась. Практическая таксономия ошибок LLM-шлюза дает командам инженеров, продуктов и финансов единый язык для описания того, что произошло и что шлюз должен делать дальше.
Flatkey соответствует этой операционной модели, поскольку его текущий публичный сайт позиционирует продукт как единую поверхность шлюза для доступа к моделям, маршрутизации, биллинга, аналитики использования и операционного контроля. Используйте эту общую поверхность для классификации сбоев, прежде чем выбирать поведение: повторная попытка, постановка в очередь, резервное переключение или отказ с закрытием.
Таксономия ошибок LLM-шлюза в одной таблице
Начинайте с класса ошибки, а не только со статуса HTTP. Одно и то же семейство статусов может означать разное у разных провайдеров, в разных SDK и для разных форм эндпоинтов.
| Класс ошибки | Общие сигналы | Повторять? | Резервное переключение? | Действие владельца |
|---|---|---|---|---|
| Аутентификация и разрешения | 401, 403, недействительный ключ, отозванный ключ, неверный проект, IP не авторизован, доступ запрещен |
Нет автоматического повтора | Нет | Сменить или исправить учетные данные, проект, список разрешенных адресов или разрешения |
| Квота и ограничение скорости | 429, ограничение скорости, квота исчерпана, лимит расходов, лимит токенов/запросов, RESOURCE_EXHAUSTED |
Иногда, с ограниченной экспоненциальной задержкой или постановкой в очередь | Только в рамках утвержденных правил по стоимости и качеству | Уменьшить параллелизм, проверить использование, увеличить лимиты или остановить расходы |
| Провайдер и транспорт | 500, 503, 529, перегрузка, тайм-аут, сброс соединения, ошибка соединения SDK |
Иногда, если операция идемпотентна и укладывается в дедлайн | Иногда, до частичного вывода и в рамках контракта | Проверить статус провайдера, исправность маршрута, бюджеты тайм-аутов и усиление повторных попыток |
| Запрос и валидация | 400, 422, некорректный JSON, недействительная модель, неподдерживаемый параметр, слишком длинный контекст |
Нет, если запрос не изменен | Редко | Исправить схему, размер промпта, форму эндпоинта или возможности модели |
| Безопасность и политика | отказ, блокировка модерацией, блокировка промпта, finishReason: SAFETY, ошибка политики контента |
Нет автоматического повтора | Нет резервного переключения в обход | Показать безопасное сообщение пользователю, залогировать контекст безопасности, запросить исправленный ввод при необходимости |
| Отмена клиентом и дедлайн | прерывание пользователем, тайм-аут клиента, дедлайн сервера, разорванный поток | Нет слепого повтора | Только если не было вывода или побочного эффекта | Остановить работу, отметить отмену, сохранить состояние частичного вывода |
Эта таксономия ошибок LLM-шлюза намеренно ориентирована на действия. Она не просто маркирует ошибки для дашбордов. Она решает, когда система может потратить больше токенов, когда она должна попросить владельца исправить состояние и когда ей следует остановиться.
Классифицируйте перед повторной попыткой
Официальная документация провайдеров поддерживает разделение этих классов. Руководство по ошибкам OpenAI различает недействительную аутентификацию, неверные ключи API, сбои списка разрешенных IP-адресов, ограничения скорости, исчерпание квоты или биллинга, ошибки сервера, перегрузку, ошибки соединения SDK, тайм-ауты SDK, некорректные запросы, отказы в доступе и исключения, связанные с ограничением скорости. В руководстве по ограничению скорости рекомендуется случайная экспоненциальная задержка, но также отмечается, что неудачные запросы все равно учитываются в поминутных лимитах.
Документация по ошибкам Anthropic разделяет invalid_request_error, authentication_error, permission_error, not_found_error, request_too_large, rate_limit_error, api_error и overloaded_error. Anthropic также документирует ограничения скорости 429 с рекомендациями по retry-after, а руководство по причинам остановки включает refusal как условие остановки на уровне модели.
Руководство по устранению неполадок Gemini рассматривает сбои аутентификации и разрешений отдельно от RESOURCE_EXHAUSTED (429), внутренних ошибок (500) и недоступности (503). Документация по ограничениям скорости Gemini описывает измерения по запросам, токенам, ежедневным запросам и расходам. Настройки безопасности Gemini также предоставляют информацию о блокировках промптов, finishReason кандидата и safetyRatings, включая finishReason со значением SAFETY, когда контент ответа заблокирован.
Эти данные приводят к простому правилу: таксономия ошибок LLM-шлюза должна нормализовать сигналы от конкретных провайдеров в поля для принятия решений, прежде чем шлюз выберет действие.
Сбои аутентификации и разрешений
Сбои аутентификации и разрешений должны немедленно прекращаться. Повторная попытка с неверным ключом или для запрещенного проекта обычно создает шум, не меняя результата.
Нормализуйте эти сигналы в класс аутентификации:
| Сигнал | Вероятное значение | Поведение шлюза |
|---|---|---|
401 недействительная аутентификация |
Ключ неверный, истек, отозван, имеет неверный формат или относится к другому проекту | Не повторять попытку; уведомить владельца ключа |
401 проблема с членством в организации или проекте |
Вызывающий не является членом требуемой организации или проекта | Не повторять попытку; направить владельцу учетной записи |
401 или 403 проблема со списком разрешенных IP-адресов или с разрешениями |
Запрос поступил из неверной сети или отсутствует доступ к конечной точке | Не повторять попытку; предоставить доказательства проблемы с разрешениями |
authentication_error или permission_error от провайдера |
Отказ в аутентификации или доступе со стороны провайдера | Не использовать резервный вариант; исправить учетные данные или предоставить доступ |
В шлюзе ошибки аутентификации должны включать owner_key, credential_id, project_id, provider, endpoint_family, requested_model и route_id. Избегайте логирования необработанных секретов. Инцидент должен отвечать на вопросы, какой ключ не сработал, какой маршрут пытался выполнить вызов и кто может это исправить.
Использование резервного варианта обычно является неверным решением при сбоях аутентификации. Если команда не одобрила одного провайдера, тихое переключение на другого может обойти процедуры закупок, границы данных или политику моделей. Контролируемый ответ — это четкий сбой, оповещение владельца и путь к устранению проблемы.
Сбои, связанные с квотами и ограничениями скорости
Сбои, связанные с квотами и ограничениями скорости, — это класс ошибок, который чаще всего страдает от неопределенной логики повторных попыток. Код 429 может означать регулирование пиковой нагрузки, ограничения на количество запросов в минуту, ограничения на количество токенов в минуту, дневные лимиты запросов, исчерпание месячного бюджета, исчерпание предоплаченного кредита или лимиты на основе расходов. У этих случаев нет единого пути восстановления.
Используйте эту таксономию ошибок LLM-шлюза для принятия решений по квотам:
| Сигнал квоты | Путь повторной попытки | Путь постановки в очередь | Путь остановки |
|---|---|---|---|
429 с Retry-After |
Учитывать заголовок, если это соответствует крайнему сроку рабочего процесса | Ставить неинтерактивные задания в очередь до времени повторной попытки | Остановить, если ожидание превышает крайний срок |
| 429 без указания времени ожидания | Использовать ограниченный случайный backoff для небольшого бюджета попыток | Уменьшить параллелизм для владельца, маршрута или семейства конечных точек | Остановить, если повторные попытки увеличивают использование в минуту |
| Ограничение по количеству токенов | Уменьшить промпт, вывод, размер пакета или параллелизм | Ставить большие задания в очередь и повторять с меньшими пакетами | Остановить, если запрос не соответствует контракту модели или контекста |
| Исчерпание расходов или кредита | Не повторять попытку автоматически | Ставить в очередь, только если финансовый владелец одобрил пополнение или увеличение бюджета | Завершить сбоем и сохранить доказательства затрат |
| Исчерпана дневная квота/квота проекта | Не выполнять повторные попытки в коротком цикле | Откладывать пакетные задания до сброса только в разрешенных случаях | Завершить сбоем для запросов, обращенных к пользователю |
Ключевым моментом является различие между временным регулированием скорости и исчерпанным бюджетом. Backoff помогает, когда провайдер просит вас замедлиться. Backoff не помогает, когда на счете нет кредита или задание не укладывается в доступный бюджет токенов.
Используйте этот раздел вместе со стратегией повторных попыток для AI API от Flatkey, если вам нужен более подробный чек-лист по повторным попыткам. Сохраняйте видимость повторных попыток в логах, чтобы финансовый и операционный отделы могли видеть дублирующиеся расходы токенов.
Сбои провайдера и транспортного уровня
Сбои провайдера и транспортного уровня отличаются от сбоев, связанных с квотами. Они означают, что запрос может быть действительным, ключ — действительным, а бюджет — доступным, но маршрут не смог завершить вызов.
Распространенные сигналы включают:
| Сигнал | Значение | Решение шлюза |
|---|---|---|
500 или api_error от провайдера |
Внутренняя ошибка на стороне провайдера | Кратковременно повторить, если операция идемпотентна; проверить статус при повторении |
503 недоступен или перегружен |
Проблемы с мощностью провайдера, техническое обслуживание или сбой | Использовать backoff или резервный вариант до получения частичного вывода |
overloaded_error от Anthropic или HTTP 529 |
Перегрузка на стороне конкретного провайдера | Рассматривать как проблему с мощностью провайдера, а не с квотой клиента |
| Ошибка подключения SDK | Сбой на пути сети, прокси, TLS, DNS или брандмауэра | Повторять попытку, только если проблема с транспортным путем, скорее всего, временная |
| Тайм-аут SDK | Запрос превысил бюджет времени ожидания | Повторять попытку, только если это позволяют крайний срок рабочего процесса и идемпотентность |
| Разрыв потоковой передачи | Частичный вывод уже может существовать | Возобновлять только при наличии явной политики потоковой передачи |
Использование резервного провайдера здесь может быть полезно, но для этого нужен контракт. Резервный маршрут должен сохранять форму конечной точки, инструменты, требования к структурированному выводу, окно контекста, границы данных, одобрение модели и ограничение по стоимости. Если потоковая передача уже выдала видимые токены, более безопасным поведением часто является остановка и отображение контролируемого сбоя вместо склеивания вывода с другого маршрута.
Используйте надежность потокового AI API для восстановления, специфичного для потоковой передачи, и используйте оценку резервной модели перед тем, как превращать ошибки провайдера в автоматические изменения маршрута.
Сбои запросов и валидации
Сбои запросов и валидации обычно не являются инцидентами на стороне провайдера. Они означают, что вызывающая сторона отправила что-то, что конечная точка не может обработать.
Примеры включают отсутствие обязательных полей, некорректный JSON, неподдерживаемые параметры, неправильное семейство конечных точек, недействительный идентификатор модели, слишком длинный контекст, неподдерживаемую схему инструмента, несовместимую модальность или входные данные файла/изображения/видео, которые не соответствуют контракту конечной точки.
Шлюз должен регистрировать следующие поля:
| Поле | Почему это важно |
|---|---|
endpoint_family |
Разделяет совместимые с OpenAI форматы чата, ответов, сообщений, Gemini, изображений и видео |
requested_model |
Идентифицирует недействительные или неподдерживаемые имена моделей |
request_schema_version |
Показывает, есть ли расхождения между клиентом и шлюзом |
parameter_name |
Указывает инженерам на неисправное поле |
input_token_estimate |
Отделяет некорректные входные данные от переполнения контекста |
client_sdk и sdk_version |
Находит проблемы миграции и совместимости |
Не повторяйте попытки при неизменных сбоях валидации. Либо преобразуйте запрос в допустимый формат, либо верните ошибку для разработчика с указанием поля, которое нужно исправить. Когда шлюз поддерживает несколько семейств конечных точек, ошибки валидации особенно важны, поскольку запрос может быть действительным для одного провайдера и недействительным для другого.
Сбои безопасности и политик
Сбои безопасности и политик требуют отдельного класса, поскольку повторные попытки и резервные варианты могут случайно ослабить защитные механизмы. Отказ по соображениям безопасности — это не простой провайдера. Блокировка модерацией — это не исчерпание квоты. Заблокированный вывод — это не повод продолжать выборку до тех пор, пока шлюз не найдет маршрут, который выдаст запрещенный контент.
Нормализуйте эти сигналы в класс безопасности:
| Сигнал | Признаки в стиле провайдера | Поведение шлюза |
|---|---|---|
| Отказ модели | Структурированные выходные данные OpenAI показывают отказы; причины остановки Anthropic включают refusal |
Представить безопасный ответ и не обходить с помощью резервного варианта |
| Блокировка модерацией | Документация по безопасности OpenAI рекомендует модерацию; ошибки изображений могут показывать moderation_blocked |
Регистрировать контекст безопасной категории и при необходимости запрашивать исправленные входные данные |
| Блокировка промпта | Настройки безопасности Gemini показывают promptFeedback.blockReason |
Вернуть контролируемое сообщение перед отправкой работы дальше по цепочке |
| Блокировка вывода | Gemini может возвращать finishReason: SAFETY и рейтинги безопасности; заблокированный контент не возвращается |
Не повторять попытки вслепую; регистрировать, что вывод был заблокирован |
| Правило политики или соответствия | Правило, специфичное для приложения: политика, закупки, границы данных, возраст или регулируемый рабочий процесс | Завершить сбоем или направить на ручную проверку |
Практическое правило простое: таксономия ошибок LLM-шлюза никогда не должна рассматривать безопасность как восстановимый сбой провайдера. Резервный вариант может быть приемлем только тогда, когда резервный маршрут сохраняет ту же или более строгую политику безопасности, и цель состоит в том, чтобы выполнить безопасную версию задачи, а не обойти блокировку.
Нормализованная запись об ошибке
Полезная таксономия ошибок LLM-шлюза превращает специфичные для провайдера сбои в одну надежную запись.
| Нормализованное поле | Примеры значений | Использование |
|---|---|---|
error_class |
auth, quota, provider, request, safety, cancelled |
Определяет группировку в руководствах и на панелях мониторинга |
http_status |
401, 403, 429, 500, 503, 529 |
Сохраняет сигнал протокола |
provider_error_type |
rate_limit_error, overloaded_error, RESOURCE_EXHAUSTED, moderation_blocked |
Сохраняет значение, специфичное для провайдера |
provider_error_code |
insufficient_quota, invalid_api_key, SAFETY |
Поддерживает точное ветвление |
retry_after_ms |
Задержка, полученная из заголовка, или null | Предотвращает угадывание времени повторной попытки |
retryable |
true или false |
Отделяет политику кода от формулировок в пользовательском интерфейсе |
fallback_allowed |
true или false |
Обеспечивает соблюдение контракта маршрута |
fail_closed_reason |
quota_exhausted, safety_block, contract_mismatch |
Объясняет, почему шлюз остановился |
requested_model and served_model |
Идентификаторы или псевдонимы моделей | Показывает, изменила ли маршрутизация поведение |
endpoint_family |
openai, anthropic, gemini, image-generation |
Делает видимыми проблемы миграции |
partial_output_committed |
true или false |
Предотвращает дублирование вывода, видимого пользователю |
usage_units and estimated_cost |
токены, изображения, секунды, доллары | Делает видимой стоимость повторной попытки |
request_id and provider_request_id |
идентификаторы шлюза и провайдера | Поддерживает тикеты в службу поддержки и разбор инцидентов |
Не сводите эту запись к одной строке вроде «Сбой вызова LLM». Этой строки недостаточно, чтобы решить, следует ли сменить ключ, подождать, пополнить счет, использовать резервный вариант, изменить промпт или остановиться.
Простой классификатор на TypeScript
Классификатору не нужно знать все детали каждого провайдера с первого дня. Начните с явных категорий и консервативного поведения по умолчанию.
type ErrorClass =
| "auth"
| "quota"
| "provider"
| "request"
| "safety"
| "cancelled"
| "unknown";
type GatewayErrorInput = {
httpStatus?: number;
providerErrorType?: string;
providerErrorCode?: string;
finishReason?: string;
stopReason?: string;
clientCancelled?: boolean;
timeout?: boolean;
};
function classifyGatewayError(error: GatewayErrorInput): ErrorClass {
const type = (error.providerErrorType || "").toLowerCase();
const code = (error.providerErrorCode || "").toLowerCase();
const stop = (error.stopReason || "").toLowerCase();
const finish = (error.finishReason || "").toLowerCase();
if (error.clientCancelled) return "cancelled";
if (error.httpStatus === 401 || error.httpStatus === 403) return "auth";
if (type.includes("auth") || type.includes("permission")) return "auth";
if (code.includes("invalid_api_key") || code.includes("ip_not_authorized")) {
return "auth";
}
if (error.httpStatus === 429) return "quota";
if (type.includes("rate_limit") || code.includes("quota")) return "quota";
if (code.includes("resource_exhausted")) return "quota";
if (stop === "refusal" || finish === "safety") return "safety";
if (code.includes("moderation") || code.includes("blocked")) return "safety";
if (error.httpStatus === 400 || error.httpStatus === 422) return "request";
if (type.includes("invalid_request") || type.includes("bad_request")) {
return "request";
}
if (error.timeout) return "provider";
if ([500, 502, 503, 504, 529].includes(error.httpStatus || 0)) {
return "provider";
}
if (type.includes("overloaded") || type.includes("api_error")) {
return "provider";
}
return "unknown";
}
Используйте это только как отправную точку. В производственных классификаторах сопоставления для конкретных провайдеров следует хранить в конфигурации, тестовых данных и отчетах об инцидентах, а не прятать только в коде приложения.
Руководство: повторная попытка, постановка в очередь, резервный вариант или отказ с закрытием
Как только класс становится известен, шлюз может выбрать действие.
| Класс | Действие по умолчанию | Условие для повторной попытки | Условие для перехода на резервный вариант | Условие для отказа в обслуживании |
|---|---|---|---|---|
| Аутентификация | Остановить и уведомить владельца | Нет, если только что не произошло обновление учетных данных | Нет | Всегда, пока не будет исправлен ключ или разрешение |
| Квота | Отложить, поставить в очередь или остановить по параметру лимита | Временное ограничение скорости соответствует крайнему сроку и бюджету попыток | Утвержденный маршрут сохраняет стоимость, качество и границы данных | Превышены расходы, кредит, дневная квота или крайний срок |
| Провайдер | Отложить или направить в обход временного сбоя провайдера | Идемпотентный вызов, нет частичного вывода, крайний срок не истек | Существует эквивалентный утвержденный маршрут | Повторяющийся сбой, частичный вывод или рабочий процесс с высоким риском |
| Запрос | Вернуть ошибку валидации, предназначенную для разработчика | Только после изменения запроса | Только когда явно выбрана совместимая конечная точка/модель | Неверная схема, переполнение контекста, неподдерживаемая возможность |
| Безопасность | Вернуть безопасный ответ или запросить исправление | Нет для неизмененного контента | Только с такой же или более строгой политикой, никогда для обхода | Заблокированный промпт/вывод, отказ, правило соответствия |
| Отменено | Остановить работу и сохранить состояние | Нет | Только если пользователь явно перезапускает | Прерывание пользователем, крайний срок, отключение клиента |
Эта таблица — операционный центр таксономии ошибок LLM-шлюза. Она сообщает шлюзу, когда дальнейшая работа безопасна, а когда она становится рискованной.
Как применить это в Flatkey
Используйте таксономию как контрольный список для развертывания, а не как разовый проект для панели управления.
- Выберите один рабочий процесс, например чат поддержки, пакетное извлечение данных, задачи оценки или трафик ассистента по коду.
- Определите разрешенные семейства конечных точек, модели, резервные маршруты и ограничения по стоимости для этого рабочего процесса.
- Нормализуйте ошибки провайдера в соответствии с полями, указанными выше.
- Сделайте сбои аутентификации и разрешений видимыми для владельца и не подлежащими повторным попыткам.
- Отделите временные ограничения скорости от исчерпания квоты, расходов и дневных лимитов.
- Требуйте наличия контракта на резервный вариант перед сменой провайдера или модели.
- Рассматривайте отказы по соображениям безопасности и модерацию как результаты политики, а не как сбои провайдера.
- Регистрируйте состояние частичного вывода перед любой повторной попыткой или переходом на резервный вариант.
- Проанализируйте данные об использовании и маршрутах в Flatkey, прежде чем расширять на другие рабочие процессы.
- Свяжите руководство по эксплуатации со страницей цен Flatkey, чтобы операторы могли проверить текущий каталог и структуру затрат.
Снимок общедоступного API цен Flatkey от 3 июля 2026 года вернул 45 строк моделей, шесть идентификаторов поставщиков и поддерживаемые семейства конечных точек, включая openai, anthropic, gemini и image-generation. Рассматривайте эти данные только как устаревшие исходные факты. Доступность моделей, цены и поведение маршрутизации следует перепроверять перед развертыванием в производственной среде.
Часто задаваемые вопросы
Что такое таксономия ошибок LLM-шлюза?
Таксономия ошибок LLM-шлюза — это нормализованный набор классов сбоев для трафика между моделью и провайдером. Она разделяет сбои аутентификации, квот, провайдера, запросов, безопасности и отмены, чтобы шлюз мог выбрать повторную попытку, постановку в очередь, переход на резервный вариант или отказ в обслуживании.
Почему не следует повторять каждый ошибочный запрос к LLM API?
Повторение каждого ошибочного запроса может усугубить инцидент. Это может усилить ограничения скорости, потратить больше токенов после исчерпания квоты, скрыть сбои учетных данных, дублировать частичный вывод или обойти блокировки безопасности. Таксономия определяет, когда повторная попытка действительно допустима.
Должны ли отказы по соображениям безопасности вызывать переход на резервный вариант?
По умолчанию нет. Отказы по соображениям безопасности, блокировки модерацией, блокировки промптов и finishReason: SAFETY следует рассматривать как результаты политики. Переход на резервный вариант никогда не должен использоваться для поиска маршрута с более слабыми мерами безопасности.
Как LLM-шлюз должен классифицировать сбои, связанные с квотами?
Отделяйте временное ограничение скорости от исчерпанных расходов, предоплаченных кредитов, дневных лимитов, лимитов токенов и лимитов проекта. При временном ограничении можно использовать ограниченную отсрочку или очереди. Исчерпанный бюджет обычно приводит к отказу в обслуживании до тех пор, пока владелец не одобрит увеличение емкости.
Как Flatkey помогает с таксономией ошибок LLM-шлюза?
Flatkey предоставляет командам единую поверхность шлюза для доступа к моделям, маршрутизации, биллинга, аналитики использования и операционного контроля. Используйте его для поддержания связи нормализованных классов ошибок с ключами владельцев, семействами конечных точек, запрашиваемыми моделями, обслуживаемыми моделями и данными об использовании.
Начните с одного рабочего процесса, определите свою таксономию ошибок LLM-шлюза, затем получите ключ и протестируйте случаи аутентификации, квот, провайдера, запросов, безопасности и отмены, прежде чем производственный трафик будет зависеть от автоматического восстановления.
