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

ZvenoAI возвращает ошибки в формате, совместимом с OpenRouter. Постройте логику повторов, используйте fallback по моделям и собирайте метрики стабильности.

Структура ошибок

Все ошибки приходят в едином envelope:

{
  "error": {
    "code": 400,
    "message": "invalid request parameters: model is required"
  }
}

Поля ответа:

• error.code — HTTP status code числом, совпадает со статусом ответа.
• error.message — человекочитаемое описание (русский/английский). Не разбирайте программно — для логики используйте error.code или metadata.
• error.metadata — опциональный объект с дополнительным контекстом. Структура зависит от типа ошибки — см. ниже известные формы.

Коды ответов и действия

Прочие 4xx/5xx (например, 404 для несуществующих ресурсов или 500 для непредвиденных внутренних ошибок) обрабатывайте по тому же envelope: error.code равен HTTP-статусу, error.message несёт описание.

Структура metadata для типовых ошибок

Поле metadata свободной формы (Record<string, unknown>), но для ряда ошибок структура зафиксирована.

Нехватка средств (HTTP 402)

Запрос, который нечем оплатить, получает 402. Причина — в metadata.reason.

{
  "error": {
    "code": 402,
    "message": "api key budget exceeded: limit=5000 RUB, spent=5000 RUB, resets at 2026-10-01T00:00:00+03:00",
    "metadata": {
      "reason": "api_key_budget_exceeded",
      "budget_limit": "5000",
      "resets_at": "2026-10-01T00:00:00+03:00"
    }
  }
}

В Chat Completions и видеогенерации провайдерский 402 наружу не выходит — там он приходит как 503.

api_key_budget_exceeded приходит только при аутентификации API-ключом, и вместе с ним — ещё два поля:

• budget_limit — лимит ключа в рублях. Приходит строкой, а не числом; хвостовых нулей в дробной части нет.
• resets_at — момент сброса лимита в формате RFC 3339 со смещением часового пояса. Период считается по московскому времени. Если у лимита нет автосброса, поля не будет: такой лимит действует всё время жизни ключа.

Moderation (HTTP 403)

{
  "error": {
    "code": 403,
    "message": "Input flagged by provider moderation",
    "metadata": {
      "reasons": ["sexual", "violence"],
      "flagged_input": "...обрезанный фрагмент входа...",
      "provider_name": "openai",
      "model_slug": "openai/gpt-4o"
    }
  }
}

Конкретные значения reasons зависят от провайдера. flagged_input обрезается до 100 символов посередине с ..., если оригинал длиннее.

Provider error (HTTP 502 / 503)

{
  "error": {
    "code": 502,
    "message": "upstream provider returned an error",
    "metadata": {
      "provider_name": "openrouter",
      "raw": {
        "error": {
          "code": "model_not_found",
          "message": "The model is currently overloaded"
        }
      }
    }
  }
}

metadata.raw — payload провайдера as-is: JSON-объект если upstream структурирован, либо строка для plain text. Размер ограничен 8 KB. Конкретная структура зависит от провайдера — не закладывайтесь на конкретные поля внутри raw, используйте его для логов и эскалаций.

Ошибки в streaming (mid-stream)

Если ошибка происходит уже после того, как поток начался, HTTP статус остаётся 200. ZvenoAI отправляет SSE-кадр с top-level error и choices[0].finish_reason = "error", после чего шлёт data: [DONE].

: OPENROUTER PROCESSING

data: {"id":"cmpl-...","object":"chat.completion.chunk","created":1735689600,"model":"openai/gpt-4o","choices":[{"index":0,"delta":{"content":"Привет"},"finish_reason":null}]}

data: {"id":"cmpl-...","object":"chat.completion.chunk","created":1735689601,"model":"openai/gpt-4o","provider":"openai","error":{"code":500,"message":"Provider disconnected unexpectedly","metadata":{"error_type":"server"}},"choices":[{"index":0,"delta":{"content":""},"finish_reason":"error"}]}

data: [DONE]

В streaming-кадре error.code — число, HTTP-статус ошибки, как и в request-error envelope. Тип ошибки лежит в error.metadata.error_type, провайдер — в поле provider кадра. Для streaming в Responses API ошибки приходят отдельными событиями: response.failed, response.error или error.

Fallback по моделям

Передавайте массив моделей, если важно гарантировать ответ. ZvenoAI выполнит запрос первой доступной моделью:

const response = await client.chat.completions.create({
  models: ['openai/gpt-4o', 'anthropic/claude-3.5-sonnet', 'google/gemini-2.5-pro'],
  messages: [{ role: 'user', content: 'Привет!' }],
})

ZvenoAI автоматически выберет доступную модель и вернёт ответ. Если ни одна не доступна — 503 с metadata.provider_name последнего попытанного.

Ретраи с exponential backoff

Повторяйте только 408, 429, 502, 503. Для 400/401/403 повторы бессмысленны — исправляйте запрос.

import OpenAI from 'openai'
import pRetry, { AbortError } from 'p-retry'

const NON_RETRYABLE = new Set([400, 401, 402, 403])

async function callLLM(messages: OpenAI.ChatCompletionMessageParam[]) {
  return pRetry(
    async () => {
      try {
        const response = await client.chat.completions.create({
          model: 'openai/gpt-4o',
          messages,
        })
        return response.choices[0].message.content
      } catch (err) {
        if (err instanceof OpenAI.APIError && NON_RETRYABLE.has(err.status ?? 0)) {
          throw new AbortError(err)
        }
        throw err
      }
    },
    { retries: 3 },
  )
}

from openai import APIStatusError
from tenacity import (
    retry, stop_after_attempt, wait_exponential, retry_if_exception,
)

NON_RETRYABLE = {400, 401, 402, 403}

def is_retryable(exc: BaseException) -> bool:
    if isinstance(exc, APIStatusError):
        return exc.status_code not in NON_RETRYABLE
    return True

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=1, max=8),
    retry=retry_if_exception(is_retryable),
)
def call_llm(messages):
    response = client.chat.completions.create(
        model="openai/gpt-4o",
        messages=messages,
    )
    return response.choices[0].message.content

operation := func() error {
    resp, err := client.CreateChatCompletion(ctx, request)
    if err != nil {
        var apiErr *openai.APIError
        if errors.As(err, &apiErr) {
            switch apiErr.HTTPStatusCode {
            case http.StatusBadRequest, http.StatusUnauthorized,
                 http.StatusPaymentRequired, http.StatusForbidden:
                return backoff.Permanent(err)
            }
        }
        return err
    }
    process(resp)
    return nil
}

err := backoff.Retry(operation, backoff.NewExponentialBackOff())

Рекомендации

• Парсите error.code (HTTP status) и error.metadata.provider_name — этого хватает для роутинга реакции.
• Для 401/403 немедленно прекращайте повторы и уведомляйте команду.
• Для 502/503 логируйте metadata.raw целиком — это сырой ответ провайдера, нужен для эскалаций.
• Используйте массив моделей (models: [...]), чтобы ZvenoAI переключился на доступную модель автоматически.
• Настройте алерты по числу 5xx/429 за интервал — это индикатор проблем.