Ошибки

Формат ответа

{
  "error": {
    "message": "Alibaba: Превышен лимит запросов. Попробуйте чуть позже или выберите другого провайдера.",
    "type": "rate_limit_exceeded",
    "code": 502,
    "metadata": {
      "error_type": "rate_limit_exceeded",
      "provider_name": "Alibaba"
    }
  }
}

Для обработки ошибок сервиса модели используйте error.type: это категория причины, а не только HTTP-статус. Например, общий 502 может сопровождаться более точной причиной — превышением лимита запросов.

• error.message — описание причины с подробностями сервиса модели, если они доступны. Эти подробности могут быть на английском. Не сравнивайте текст в коде.
• error.type — стабильная категория ошибки из справочника ниже или локальный код GoRouter.
• error.code — исходный строковый или числовой код сервиса модели. Для локальных ошибок совпадает с error.type.
• error.metadata.error_type — нормализованная категория ошибки сервиса модели.
• error.metadata.provider_name и provider_code — имя провайдера и его код ошибки, если они доступны.
• Retry-After — минимальная задержка перед повтором, если её передал сервис.

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

HTTP-статусы

HTTP-статус сохраняется от сервиса модели. Исключение — распознанный отказ по приватности: он возвращается как 403 с кодом no_allowed_providers.

Другие статусы также возможны. Неизвестная причина получает error.type: "unmapped"; исходный статус сохраняется.

Ошибки и inference-авторизации

Если провайдер явно отклонил параметры до генерации и нет данных о выполнении или расходе, GoRouter освобождает авторизацию: X-GoRouter-Billing-Status: released. Один HTTP-статус 400 без подтверждённой причины недостаточен для освобождения. При таймауте или обрыве соединения запрос мог уже выполняться: запрос остаётся на сверке (pending) до получения стоимости. Через 35 минут авторизация перестаёт уменьшать доступный баланс, но поздний подтверждённый счёт всё равно списывается и может создать долг. Не отправляйте повторные запросы подряд только из-за ошибки таймаута в клиенте.

Категории ошибок сервиса модели

Контекст и токены

Доступ и средства

Лимиты и доступность

Запрос и содержимое

Изображения

Неизвестная причина

unmapped — причина не относится к известным категориям или не раскрыта сервисом. Учитывайте HTTP-статус и не повторяйте запрос бесконечно.

Локальные ошибки GoRouter

Для этих ошибок error.code и error.type совпадают.

Приватность

При privacy_policy_violation и no_allowed_providers проверьте настройки приватности. Не каждый 403 связан с приватностью. При распознанном отказе по политике приватности резерв освобождается без списания. Подробнее: Приватность и провайдеры.

Защита чувствительных данных

Ошибки не содержат найденные значения. Подробнее: Защита чувствительных данных.

Ошибки при HTTP 200 и в потоке

Успешный HTTP-статус не гарантирует успешную генерацию. Проверяйте содержимое ответа:

• Chat Completions: error в корне или choices[].error, в том числе при finish_reason: "error".
• Responses: error в ответе или response.error в событиях response.failed / response.error.
• SSE: ошибка может прийти после нескольких токенов при уже открытом HTTP 200.

GoRouter сохраняет оболочку ответа и уже полученный текст. Категория доступна в соответствующем объекте error.type. Обычный finish_reason: "length" сам по себе не преобразуется в ошибку.

data: {"choices":[{"index":0,"delta":{"content":"Начало ответа"}}]}

data: {"error":{"code":429,"type":"rate_limit_exceeded","message":"Превышен лимит запросов. Попробуйте чуть позже или выберите другого провайдера.","metadata":{"error_type":"rate_limit_exceeded"}},"choices":[{"index":0,"delta":{},"finish_reason":"error"}]}

data: [DONE]

Не перезапускайте генерацию автоматически после частичного ответа: повтор создаёт новый запрос и может привести к дополнительной оплате. Разрыв соединения или тайм-аут не гарантирует остановку работы провайдера. См. Streaming.

Повторные запросы

Для временных лимитов и сбоев используйте ограниченное число попыток с увеличивающейся задержкой. Учитывайте Retry-After: он может содержать число секунд или HTTP-дату. Для 400, 401, 402, 403 сначала устраните причину. Если 502 содержит более точную категорию, решение о повторе принимайте по ней.

function retryDelayMs(response: Response): number | null {
  const value = response.headers.get("retry-after");
  if (!value) return null;
  if (/^\d+$/.test(value)) return Number(value) * 1000;
  const until = Date.parse(value);
  return Number.isNaN(until) ? null : Math.max(0, until - Date.now());
}

// Для обычного JSON-ответа. SSE разбирайте по событиям.
const payload = await response.json();
const error = payload.error ?? payload.response?.error
  ?? payload.choices?.find((choice: { error?: unknown }) => choice.error)?.error;

if (!response.ok || error) {
  console.error(error?.type ?? "unknown", error?.message ?? "Ошибка запроса");
  const delayMs = retryDelayMs(response);
  // Решение о повторе зависит от причины и наличия частичного результата.
}