Ошибки GPT API: 401, 402, 429 и 5xx

Ошибки конфигурации и временные сбои требуют разной реакции. Бесконечный retry не исправляет ключ или баланс, создаёт нагрузку и усложняет диагностику.

Сначала проверьте путь подключения

Если интеграция ещё не настроена, зарегистрируйтесь, пополните баланс, дождитесь зачисления и создайте ключ в разделе API-ключей. Для универсальной работы после пополнения используйте gpt-5.6-terra; для экономичного теста — gpt-5.6-luna. Актуальный model ID и тариф сверяйте на странице цен.

Параметры запроса:

• Base URL: https://api.apiprovider.pro/v1;
• RU Base URL: https://api.ru.apiprovider.pro/v1;
• авторизация: Authorization: Bearer YOUR_API_KEY;
• текстовый endpoint: POST /chat/completions.

Начните с минимального запроса. Не вставляйте ключ прямо в команду, сохраняемую в shell history, и не записывайте Authorization в логи.

401: ошибка авторизации

Проверьте наличие Bearer-заголовка, доступность переменной окружения процессу, лишние пробелы и правильный Base URL. Автоматически повторять 401 не нужно: без исправления секрета или конфигурации ответ не изменится.

402: недостаточно баланса

Проверьте баланс, выбранную модель и ожидаемый объём запроса. Повторять запрос до изменения состояния не нужно. Пополните баланс, дождитесь зачисления и выполните один новый тест.

429: слишком высокая частота

Уменьшите параллелизм, поставьте задачи в очередь и ограничьте всплески. Если ответ содержит Retry-After, используйте указанную сервером паузу. Иначе примените растущую задержку со случайным разбросом.

Практичный предел — не более трёх повторов после исходной попытки. После исчерпания лимита остановите поток или верните задачу в контролируемую очередь.

5xx: временная серверная ошибка

Сначала исключите неверный URL и маршрут. Затем для безопасной операции выполните до трёх повторов с растущей паузой и jitter. Если ошибка сохраняется, остановите автоматический поток, покажите понятный fallback и соберите безопасные диагностические данные.

Не повторяйте операцию с внешним побочным эффектом, если приложение не гарантирует идемпотентность. Иначе восстановление сети может привести к повторной публикации, записи или уведомлению.

Пример ограниченного retry

import random
import time
import requests

RETRYABLE = {429, 500, 502, 503, 504}
MAX_RETRIES = 3


def post_with_retry(url, headers, payload):
    for attempt in range(MAX_RETRIES + 1):
        response = requests.post(url, headers=headers, json=payload, timeout=60)
        if response.status_code not in RETRYABLE:
            response.raise_for_status()
            return response
        if attempt == MAX_RETRIES:
            response.raise_for_status()

        retry_after = response.headers.get("Retry-After")
        delay = float(retry_after) if retry_after and retry_after.isdigit() else 2 ** attempt + random.uniform(0, 0.5)
        time.sleep(delay)

Безопасное логирование

Записывайте время, HTTP-статус, model ID, длительность, число повторов и безопасный идентификатор задачи. Не логируйте ключ, заголовок Authorization, полные пользовательские сообщения, сырые персональные данные и секреты конфигурации. Подробнее: безопасность API-ключа.

Для production добавьте общий дедлайн задачи, очередь, метрики, circuit breaker или аналогичную остановку потока и контролируемый fallback. Полный список — в production-чек-листе.

Частые вопросы

Какие ошибки можно повторять?

Только временные 429 и 5xx, ограниченное число раз. 401 и 402 сначала требуют изменения ключа, конфигурации или баланса.

Что важнее при 429: backoff или Retry-After?

Если сервер прислал Retry-After, ориентируйтесь на него. Возвращайте задачи постепенно, чтобы не создать повторный всплеск.

Что делать после трёх неудачных повторов?

Остановить автоматические попытки, применить fallback и сохранить безопасные технические данные для диагностики.

Настройте устойчивую обработку ошибок

Откройте документацию, проверьте минимальный запрос и добавьте ограниченные повторы только для временных ошибок. Защитите ключи и пользовательские данные до включения логов.