Документация/Обработка ошибок

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

В этом руководстве описаны формат ответа об ошибках 诺玛AI, распространённые сценарии ошибок и рекомендуемые стратегии их обработки.

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

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

Код

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

Коды состояния HTTP#

Код состояния

Тип

Описание

Нужно ли повторять

`400`

`invalid_request_error`

Ошибка в параметрах запроса

❌ Исправьте параметры и повторите

`401`

`authentication_error`

API Key недействителен или отсутствует

❌ Проверьте API Key

`403`

`permission_error`

Недостаточно прав

❌ Проверьте права аккаунта

`404`

`not_found_error`

Модель или ресурс не существует

❌ Проверьте ID модели

`429`

`rate_limit_error`

Сработало ограничение частоты запросов

✅ Подождите и повторите

`500`

`internal_error`

Внутренняя ошибка сервера

✅ Повторите позже

`502`

`upstream_error`

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

✅ Смените модель или повторите

`503`

`service_unavailable`

Сервис временно недоступен

✅ Повторите позже

Распространённые ошибки и решения#

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

Код

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

Решение:

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

429 — Ограничение частоты запросов

Решение:

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

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

Решение:

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

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

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

Код

import time
import random
from openai import OpenAI, APIError, RateLimitError, APIConnectionError
 
client = OpenAI(
    base_url="https://as.apinoma.com/v1",
    api_key="<ваш APINOMA_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://as.apinoma.com/v1",
    api_key="<ваш APINOMA_API_KEY>",
    timeout=60.0,  # таймаут 60 секунд
    max_retries=3  # встроенные повторы SDK
)

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

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

Различайте повторяемые и неповторяемые ошибки — 4xx обычно требуют изменения запроса, 5xx можно повторять
Используйте экспоненциальную задержку — избегайте частых повторов при ограничении частоты
Задавайте максимальное число повторов — чтобы не повторять бесконечно
Записывайте журнал ошибок — для удобства диагностики проблем
Настройте отказоустойчивость — используйте параметр `provider.fallback` 诺玛AI для автоматического переключения моделей
Следите за частотой ошибок — отслеживайте тренды ошибок в консоли

Последнее обновление: 23 июня 2026 г.