Руководства

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

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

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

ZvenoAI возвращает ошибки в структурированном JSON формате. Каждая ошибка содержит код, сообщение и дополнительную информацию.

{
  "code": "ERR_INVALID_REQUEST",
  "message": "invalid request parameters: model is required",
  "param": "model",
  "sequence_number": 12345
}

Поля ответа:

code — код ошибки (например, ERR_INVALID_REQUEST)
message — человекочитаемое описание ошибки
param — опциональное поле с именем параметра, вызвавшего ошибку
sequence_number — уникальный порядковый номер ошибки для отслеживания

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

HTTP	Код ошибки	Причина	Реакция
400	ERR_INVALID_REQUEST	Некорректный запрос (валидируйте payload).	Не повторяйте — исправьте запрос.
401	ERR_INVALID_AUTH ERR_INCORRECT_API_KEY ERR_ORGANIZATION_REQUIRED	Неверные учетные данные или API ключ.	Не повторяйте — обновите ключ и уведомьте команду.
403	ERR_IP_NOT_AUTHORIZED ERR_COUNTRY_NOT_SUPPORTED ERR_PERMISSION_DENIED	Доступ запрещен (IP не авторизован, страна не поддерживается, нет прав).	Не повторяйте — проверьте настройки доступа.
404	ERR_NOT_FOUND	Ресурс не найден (модель, пользователь и т.д.).	Не повторяйте — проверьте корректность идентификатора.
409	ERR_CONFLICT	Конфликт (ресурс уже существует).	Не повторяйте — используйте существующий ресурс или измените параметры.
402	ERR_INSUFFICIENT_FUNDS ERR_QUOTA_EXCEEDED	Недостаточно средств на счете или превышена квота.	Пополните баланс или дождитесь обновления квоты.
429	ERR_RATE_LIMIT ERR_SLOW_DOWN	Достигнут лимит запросов/токенов.	Используйте exponential backoff и повторите запрос.
500	ERR_SERVER_ERROR ERR_ENGINE_OVERLOADED	Внутренняя ошибка сервера или перегрузка движка модели.	Повторите запрос через 2-5 секунд.

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 автоматически выберет доступную модель и вернет ответ.

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

Если ошибка происходит уже после того, как поток начался, HTTP статус уже отправлен как 200. В этом случае ZvenoAI отправляет SSE-кадр с полем error на верхнем уровне и завершает поток.

: 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","error":{"code":"server_error","message":"Provider disconnected unexpectedly"},"choices":[{"index":0,"delta":{"content":""},"finish_reason":"error"}]}

data: [DONE]

Ретраи с exponential backoff

Реализуйте повторные попытки для 429 и 5xx ошибок. Ниже примеры для различных SDK:

import pRetry from 'p-retry';

async function callLLM(messages: any[]) {
  return pRetry(
    async () => {
      const response = await client.chat.completions.create({
        model: 'openai/gpt-4o',
        messages,
      });
      return response.choices[0].message.content;
    },
    {
      retries: 3,
      onFailedAttempt: (error) => {
        if (error.status === 401) throw error; // не повторяем
        if (error.status === 400) throw error;
      },
    }
  );
}

Связанные ресурсы

Rate limits и квоты

Узнайте лимиты ZvenoAI и настройте метрики по токенам.

Streaming (SSE)

Как корректно обрабатывать потоковые ответы и ошибки по ходу стрима.

Python SDK

Примеры обработки ошибок в Python.

Руководства

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

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

{
  "code": "ERR_INVALID_REQUEST",
  "message": "invalid request parameters: model is required",
  "param": "model",
  "sequence_number": 12345
}

Поля ответа:

code — код ошибки (например, ERR_INVALID_REQUEST)
message — человекочитаемое описание ошибки
param — опциональное поле с именем параметра, вызвавшего ошибку
sequence_number — уникальный порядковый номер ошибки для отслеживания

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

HTTP	Код ошибки	Причина	Реакция
400	ERR_INVALID_REQUEST	Некорректный запрос (валидируйте payload).	Не повторяйте — исправьте запрос.
401	ERR_INVALID_AUTH ERR_INCORRECT_API_KEY ERR_ORGANIZATION_REQUIRED	Неверные учетные данные или API ключ.	Не повторяйте — обновите ключ и уведомьте команду.
403	ERR_IP_NOT_AUTHORIZED ERR_COUNTRY_NOT_SUPPORTED ERR_PERMISSION_DENIED	Доступ запрещен (IP не авторизован, страна не поддерживается, нет прав).	Не повторяйте — проверьте настройки доступа.
404	ERR_NOT_FOUND	Ресурс не найден (модель, пользователь и т.д.).	Не повторяйте — проверьте корректность идентификатора.
409	ERR_CONFLICT	Конфликт (ресурс уже существует).	Не повторяйте — используйте существующий ресурс или измените параметры.
402	ERR_INSUFFICIENT_FUNDS ERR_QUOTA_EXCEEDED	Недостаточно средств на счете или превышена квота.	Пополните баланс или дождитесь обновления квоты.
429	ERR_RATE_LIMIT ERR_SLOW_DOWN	Достигнут лимит запросов/токенов.	Используйте exponential backoff и повторите запрос.
500	ERR_SERVER_ERROR ERR_ENGINE_OVERLOADED	Внутренняя ошибка сервера или перегрузка движка модели.	Повторите запрос через 2-5 секунд.

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 автоматически выберет доступную модель и вернет ответ.

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

: 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","error":{"code":"server_error","message":"Provider disconnected unexpectedly"},"choices":[{"index":0,"delta":{"content":""},"finish_reason":"error"}]}

data: [DONE]

Ретраи с exponential backoff

Реализуйте повторные попытки для 429 и 5xx ошибок. Ниже примеры для различных SDK:

import pRetry from 'p-retry';

async function callLLM(messages: any[]) {
  return pRetry(
    async () => {
      const response = await client.chat.completions.create({
        model: 'openai/gpt-4o',
        messages,
      });
      return response.choices[0].message.content;
    },
    {
      retries: 3,
      onFailedAttempt: (error) => {
        if (error.status === 401) throw error; // не повторяем
        if (error.status === 400) throw error;
      },
    }
  );
}

Связанные ресурсы

Rate limits и квоты

Узнайте лимиты ZvenoAI и настройте метрики по токенам.

Streaming (SSE)

Как корректно обрабатывать потоковые ответы и ошибки по ходу стрима.

Python SDK

Примеры обработки ошибок в Python.

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

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

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

Fallback по моделям

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

Ретраи с exponential backoff

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

Связанные ресурсы

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

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

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

Fallback по моделям

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

Ретраи с exponential backoff

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

Связанные ресурсы