Справка

Коды ошибок

Справочник по кодам ошибок API и рекомендации по их обработке.

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

Все ошибки API возвращаются в едином формате:

Response401

Unauthorized

{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}

Поля ошибки

messageЧеловекочитаемое описание ошибки

typeКатегория ошибки (authentication_error, rate_limit_error, etc.)

codeМашиночитаемый код ошибки

paramПараметр, вызвавший ошибку (если применимо)

Таблица кодов

400Bad Request

Неверный формат запроса или отсутствуют обязательные параметры.

Решение: Проверьте JSON синтаксис и наличие всех required полей.

401Unauthorized

Неверный или отсутствующий API ключ.

Решение: Проверьте заголовок Authorization и правильность ключа.

402Payment Required

Недостаточно средств на балансе.

Решение: Пополните баланс в личном кабинете.

403Forbidden

Доступ запрещён. API ключ заблокирован или отозван.

Решение: Создайте новый ключ или обратитесь в поддержку.

404Not Found

Запрошенная модель или ресурс не найден.

Решение: Проверьте ID модели. Используйте /v1/models для списка доступных.

429Too Many Requests

Превышен лимит запросов (rate limit).

Решение: Снизьте частоту запросов или обновите тарифный план.

500Internal Server Error

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

Решение: Повторите запрос позже. Если ошибка повторяется - обратитесь в поддержку.

503Service Unavailable

Сервис временно недоступен (перегрузка или обслуживание).

Решение: Повторите запрос через несколько минут.

Примеры частых ошибок

Rate Limit (429)

Response429

{
  "error": {
    "message": "Rate limit exceeded. Please slow down your requests.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "param": null
  }
}

Insufficient Funds (402)

Response402

{
  "error": {
    "message": "Insufficient funds. Please top up your balance.",
    "type": "payment_error",
    "code": "insufficient_funds",
    "param": null
  }
}

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

Python

error_handling.py

1from openai import OpenAI, APIError, RateLimitError, AuthenticationError
2
3client = OpenAI(
4    base_url="https://api.42gpu.ru/v1",
5    api_key="sk-air-your-api-key"
6)
7
8try:
9    response = client.chat.completions.create(
10        model="gpt-4-turbo",
11        messages=[{"role": "user", "content": "Hello"}]
12    )
13except AuthenticationError as e:
14    print(f"Ошибка авторизации: {e}")
15    # Проверьте API ключ
16except RateLimitError as e:
17    print(f"Rate limit: {e}")
18    # Подождите и повторите
19    import time
20    time.sleep(60)
21except APIError as e:
22    print(f"API ошибка: {e}")
23    # Обработка других ошибок

JavaScript

error_handling.js

1import OpenAI from 'openai';
2
3const client = new OpenAI({
4  baseURL: 'https://api.42gpu.ru/v1',
5  apiKey: 'sk-air-your-api-key',
6});
7
8async function makeRequest() {
9  try {
10    const response = await client.chat.completions.create({
11      model: 'gpt-4-turbo',
12      messages: [{ role: 'user', content: 'Hello' }],
13    });
14    return response;
15  } catch (error) {
16    if (error instanceof OpenAI.AuthenticationError) {
17      console.error('Invalid API key');
18    } else if (error instanceof OpenAI.RateLimitError) {
19      console.error('Rate limit exceeded, retrying...');
20      await new Promise(resolve => setTimeout(resolve, 60000));
21      return makeRequest();
22    } else if (error instanceof OpenAI.APIError) {
23      console.error(`API Error: ${error.status} - ${error.message}`);
24    }
25    throw error;
26  }
27}

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

Для ошибок 429 (rate limit) и 503 (service unavailable) рекомендуется использовать exponential backoff:

retry.py

1import time
2from openai import OpenAI, RateLimitError
3
4client = OpenAI(
5    base_url="https://api.42gpu.ru/v1",
6    api_key="sk-air-your-api-key"
7)
8
9def make_request_with_retry(max_retries=3):
10    for attempt in range(max_retries):
11        try:
12            return client.chat.completions.create(
13                model="gpt-4-turbo",
14                messages=[{"role": "user", "content": "Hello"}]
15            )
16        except RateLimitError:
17            if attempt < max_retries - 1:
18                wait_time = 2 ** attempt  # Exponential backoff
19                print(f"Rate limited. Waiting {wait_time}s...")
20                time.sleep(wait_time)
21            else:
22                raise
23
24response = make_request_with_retry()

Совет: OpenAI SDK автоматически делает retry для временных ошибок. Для кастомной логики используйте библиотеки вроде tenacity (Python) или p-retry (JavaScript).

Best Practices

Всегда обрабатывайте ошибки

Никогда не игнорируйте ошибки API. Логируйте их для отладки и показывайте пользователям понятные сообщения.

Используйте timeout

Устанавливайте разумные таймауты (30-60 секунд) для запросов к API, чтобы избежать зависания приложения.

Мониторьте ошибки

Отслеживайте процент ошибок в вашем приложении. Резкий рост может указывать на проблемы с API ключом или превышение лимитов.

Graceful degradation

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