Skip to Content
ДокументацияРуководстваОбработка ошибок

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

Данное руководство описывает формат ответов об ошибках OfoxAI API, типичные сценарии ошибок и рекомендуемые стратегии обработки.

Формат ответа об ошибке

Все ответы об ошибках следуют единому формату JSON:

{
  "error": {
    "code": "invalid_api_key",
    "message": "Указанный API Key недействителен, проверьте и повторите попытку.",
    "type": "authentication_error"
  }
}

HTTP-коды состояния

КодТипОписаниеПовторить?
400invalid_request_errorОшибка параметров запроса❌ Исправьте параметры и повторите
401authentication_errorAPI Key недействителен или отсутствует❌ Проверьте API Key
403permission_errorНедостаточно прав❌ Проверьте права аккаунта
404not_found_errorМодель или ресурс не найден❌ Проверьте ID модели
429rate_limit_errorСработал лимит запросов✅ Подождите и повторите
500internal_errorВнутренняя ошибка сервера✅ Повторите позже
502upstream_errorОшибка вышестоящего провайдера✅ Смените модель или повторите
503service_unavailableСервис временно недоступен✅ Повторите позже

Типичные ошибки и решения

401 — Недействительный API Key

{"error": {"code": "invalid_api_key", "message": "The API key provided is invalid."}}

Решение:

  • Проверьте правильность копирования API Key (включая префикс sk-)
  • Убедитесь, что ключ не истек и не отключен
  • Проверьте корректность загрузки переменных окружения

429 — Лимит запросов

{"error": {"code": "rate_limit_exceeded", "message": "Rate limit reached. Please retry after 1s."}}

Решение:

  • Проверьте заголовок x-ratelimit-reset-requests в ответе
  • Реализуйте повторные попытки с экспоненциальным откатом
  • Для получения более высокой квоты свяжитесь с поддержкой

502 — Ошибка вышестоящего провайдера

{"error": {"code": "upstream_error", "message": "The upstream provider returned an error."}}

Решение:

  • Используйте аварийное переключение для автоматического перехода на резервную модель
  • Повторите позже
  • Проверьте страницу статуса провайдера модели

Стратегия повторных попыток

Рекомендуется использовать стратегию экспоненциального отката (Exponential Backoff):

retry.py
import time
import random
from openai import OpenAI, APIError, RateLimitError, APIConnectionError
 
client = OpenAI(
    base_url="https://api.ofox.ai/v1",
    api_key="<Ваш OFOXAI_API_KEY>"
)
 
def chat_with_retry(max_retries=5, **kwargs):
    """Обертка для повторных попыток с экспоненциальным откатом"""
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)
 
        except RateLimitError:
            # 429: подождать и повторить
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"Сработал лимит, ожидание {wait:.1f}s перед повтором...")
            time.sleep(wait)
 
        except APIConnectionError:
            # Ошибка сети: короткое ожидание и повтор
            wait = 2 ** attempt
            print(f"Ошибка соединения, ожидание {wait}s перед повтором...")
            time.sleep(wait)
 
        except APIError as e:
            if e.status_code and e.status_code >= 500:
                # 5xx: ошибка сервера, повторить
                wait = 2 ** attempt
                time.sleep(wait)
            else:
                # 4xx: ошибка клиента, не повторять
                raise
 
    raise Exception(f"Не удалось выполнить после {max_retries} попыток")
 
# Использование
response = chat_with_retry(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Здравствуйте"}]
)

Настройка таймаута

Рекомендуется устанавливать разумное время ожидания для вызовов API:

# Python OpenAI SDK
client = OpenAI(
    base_url="https://api.ofox.ai/v1",
    api_key="<Ваш OFOXAI_API_KEY>",
    timeout=60.0,  # Таймаут 60 секунд
    max_retries=3  # Встроенные повторные попытки SDK
)
// TypeScript OpenAI SDK
const client = new OpenAI({
  baseURL: 'https://api.ofox.ai/v1',
  apiKey: '<Ваш OFOXAI_API_KEY>',
  timeout: 60000,  // Таймаут 60 секунд
  maxRetries: 3    // Встроенные повторные попытки SDK
})

Для потоковых запросов рекомендуется использовать более длительный таймаут (120-300 секунд), так как модели может потребоваться больше времени для генерации полного контента.

Лучшие практики

  1. Различайте повторяемые и неповторяемые ошибки — 4xx обычно требуют исправления запроса, 5xx можно повторить
  2. Используйте экспоненциальный откат — избегайте частых повторов при ограничении скорости
  3. Устанавливайте максимальное количество попыток — предотвращайте бесконечные повторы
  4. Ведите лог ошибок — для удобства диагностики проблем
  5. Настройте аварийное переключение — используйте параметр provider.fallback OfoxAI для автоматического переключения моделей
  6. Мониторьте частоту ошибок — отслеживайте тренды ошибок в консоли
Last updated on
Структурированный выводМаршрутизация провайдеров