Ошибки

При ошибке API сначала проверьте HTTP-статус, затем код и тело ответа. Исправимые ошибки 400, 401, 402, 403, 404 и 405 не нужно повторять без изменения запроса или состояния аккаунта. Для 429 и временных 502/503 допустимы только ограниченные повторы с задержкой и случайным разбросом.

Формат ошибки зависит от того, на каком слое она возникла: в шлюзе, при проверке доступа или у поставщика модели. Поэтому не стройте обработку только на одном поле error.code и не ожидайте, что любой ответ поставщика будет приведён к единой схеме.

Коды ошибок

Ниже перечислены статусы и коды, которые подтверждены текущей реализацией AI Gateway. Конкретное имя кода гарантировано только для того слоя, который его формирует; на другом маршруте тот же HTTP-статус может прийти с другим телом.

Проверяйте статус до разбора тела: ответ не всегда содержит JSON, а JSON не всегда имеет одинаковую вложенность. Практические правила по ключам и лимитам собраны отдельно в статьях об авторизации и лимитах API.

Retry-After

Если в ответе 429, 502 или 503 присутствует заголовок Retry-After, используйте указанную им паузу. AI Gateway не гарантирует этот заголовок на каждом маршруте и для каждой ошибки, поэтому клиенту нужен собственный запасной алгоритм.

Подходящий базовый порядок:

1. Ограничьте общее число попыток, например четырьмя вместе с исходным запросом.
2. Для 429 и временных 502/503 увеличивайте задержку после каждой неудачи.
3. Добавляйте случайный разброс, чтобы несколько процессов не повторяли запрос одновременно.
4. Останавливайтесь после лимита попыток и возвращайте управляемую ошибку вызывающей системе.

const retryableStatuses = new Set([429, 502, 503]);
const maxAttempts = 4;

for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
  const response = await callSmartaipack();

  if (!retryableStatuses.has(response.status)) {
    return response;
  }

  if (attempt === maxAttempts - 1) {
    return response;
  }

  const retryAfter = response.headers.get("retry-after");
  const fallbackMs = 500 * 2 ** attempt;
  const jitterMs = Math.floor(Math.random() * 250);
  const delayMs = retryAfter
    ? parseRetryAfter(retryAfter)
    : fallbackMs + jitterMs;

  await wait(delayMs);
}

callSmartaipack, parseRetryAfter и wait здесь условные функции. Ограничьте максимальную паузу и проверяйте, что Retry-After разобран корректно. Не применяйте эту схему к 400, 401, 402, 403, 404 или 405: сначала устраните причину.

Ошибки поставщика

После допуска запроса AI Gateway передаёт его выбранному поставщику модели. Если поставщик вернул ошибочный HTTP-статус и тело ответа, шлюз может передать их клиенту без приведения к единому формату ошибки.

Поэтому обработчик должен сохранять отдельно:

• HTTP-статус;
• Content-Type;
• доступный код, тип и сообщение из тела;
• путь и публичный идентификатор модели;
• время запроса;
• request ID, только если он действительно присутствует в заголовке или ответе.

Не делайте вывод о причине только по тексту сообщения. Сначала отделите локальный отказ доступа от ответа поставщика, затем сопоставьте событие с журналом использования и аналитикой.

Ошибки потока

До начала потока

Если ошибка произошла до успешного начала SSE-потока, клиент получает обычный HTTP-ответ с ошибочным статусом. Обрабатывайте его по таблице выше: исправьте причины 400, 401, 402, 403, 404 или 405, а 429, 502 и 503 повторяйте только ограниченно.

Не начинайте разбор SSE-событий, пока не проверили HTTP-статус и Content-Type. Настройка клиента и признаки корректного завершения описаны в руководстве по потоковым ответам.

После начала потока

После отправки успешных HTTP-заголовков статус уже нельзя заменить на новый ошибочный HTTP-статус. Ошибка может проявиться событием в потоке, преждевременным завершением соединения или отсутствием ожидаемого признака окончания.

Уже начатый, но не завершившийся поток считайте неполным, даже если клиент получил часть текста. Сохраните полученные фрагменты отдельно от признака успешного результата. Если выполняете новый запрос, не склеивайте его ответ с предыдущим частичным потоком и не выдавайте объединённый текст как один ответ модели.

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

Типы ошибок

Лимиты

402 insufficient_balance означает, что запросы остановлены из-за баланса. Повторы не помогут, пока состояние организации не изменится. 429 означает ограничение частоты или защиту от большого числа отклонённых запросов: уменьшите параллелизм и используйте конечные повторы. Подробности — в статье «Лимиты API».

Авторизация

При 401 проверьте, что заголовок имеет вид Authorization: Bearer <КЛЮЧ>, секрет не содержит лишних кавычек или пробелов, ключ не истёк и не был заменён. Повтор с тем же недействительным ключом только создаёт дополнительные отказы. Порядок проверки разобран в статье «Авторизация в API».

Частота и доступность

429 относится к частоте запросов или защите шлюза, а 502/503 — к временной недоступности поставщика, проверки допуска, маршрута либо свободного обработчика. Эти статусы можно повторять ограниченно, но устойчивый 503 требует диагностики, а не бесконечного цикла.

Валидация

При 400 сначала проверьте синтаксис JSON и поле model. Затем убедитесь, что модель опубликована для выбранного пути. Например, вариант модели у одного поставщика может работать через Chat Completions, но не поддерживать Messages.

Для непубликованного пути шлюз возвращает 404 ENDPOINT_NOT_SUPPORTED. Если путь существует, но вызван неподходящим методом, возможен 405; тело такого ответа зависит от маршрута.

Общие

Неизвестную ошибку разбирайте от общего к частному: доступен ли HTTP-статус, начался ли поток, есть ли JSON-тело, присутствует ли код, появился ли запрос в журнале. Отсутствие записи в кабинете само по себе не доказывает конкретную причину: запрос мог быть отклонён до вызова модели.

Недоступность модели

Сначала откройте список моделей и скопируйте актуальный публичный идентификатор. Модель должна быть опубликована именно для используемого API-протокола.

Если получен 400 model_not_published, проверьте одновременно model и путь. Если получен 403 model_not_allowed, модель опубликована, но не разрешена этому ключу. Если выбранный вариант поставщика не совместим с путём, возможен 400 PROVIDER_ENDPOINT_NOT_SUPPORTED или другая ошибка совместимости без такого кода на другом слое.

Не подменяйте модель автоматически при любой ошибке: это может изменить характеристики, стоимость и поведение ответа. Сначала установите причину и выберите доступную модель осознанно.

Форматы по API

Chat Completions

Локальные ошибки входного маршрутизатора обычно имеют объект error с code и message; некоторые из них также содержат request_id. Однако ответ поставщика может иметь другую схему или даже не быть JSON.

{
  "error": {
    "code": "UPSTREAM_UNAVAILABLE",
    "message": "Upstream is unavailable",
    "request_id": "..."
  }
}

Responses

Проверки JSON, модели, метода и допуска обычно возвращают объект error, но регистр кодов различается между слоями. Например, INVALID_JSON формирует внешний маршрутизатор, а model_not_published — проверка допуска. Не нормализуйте их сравнением без учёта регистра.

{
  "error": {
    "code": "INVALID_JSON",
    "message": "Request body must be valid JSON"
  }
}

Messages

Для некоторых ошибок совместимости Messages возвращает форму с верхнеуровневым type и вложенным error.type. Другие локальные отказы могут использовать обычный объект error, а ответы поставщика — собственную форму.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "code": "PROVIDER_ENDPOINT_NOT_SUPPORTED",
    "message": "..."
  }
}

Во всех трёх API сначала проверяйте HTTP-статус, затем безопасно пробуйте разобрать JSON и только после этого читайте доступные поля. Актуальные пути и тела запросов смотрите в справочнике API.

Диагностика

Что записать у себя

Для каждого неуспешного вызова запишите:

• дату и время с часовым поясом;
• путь и HTTP-метод;
• публичный model из исходного запроса;
• HTTP-статус и Content-Type ответа;
• доступные code, type и короткое сообщение;
• номер попытки и фактическую задержку перед повтором;
• начался ли поток, сколько данных получено и был ли штатный признак завершения;
• request ID, только если он присутствует в заголовке или теле ответа.

Сверьте запрос в Использовании, а частоту и распределение ошибок — в Аналитике. Для проверки доступности конкретной модели используйте раздел Модели.

Что передать поддержке

В обращение через поддержку включите время, путь, метод, модель, HTTP-статус, доступный код, число попыток и признак начала потока. Приложите идентификатор запроса только при его наличии и небольшой фрагмент ответа, достаточный для распознавания ошибки.

Не отправляйте полный API-ключ или заголовок Authorization. Для воспроизведения достаточно безопасных параметров запроса и описания результата. Если ошибка повторяется, укажите, была ли она постоянной или возникала только под нагрузкой.