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

Обработка ошибок и повторы

Ветвление по кодам статуса и повторы с экспоненциальной задержкой — устойчивость к лимитам и сбоям источников.

Два правила: ветвитесь по HTTP-статусу и полю type/status (сообщения локализованы — сравнение текста сломается) и повторяйте только то, что имеет смысл повторять — некорректный запрос не станет корректным от повторения.

Действия по кодам статуса

HTTP	Типичная причина	Действие
400	Некорректное тело, нет полей	Исправьте запрос. Не повторяйте.
401 / 403	Ключ недействителен/отключён, IP заблокирован	Проверьте ключ и настройки. Не повторяйте.
402	Исчерпан баланс или квота ключа	Пополните баланс или лимит. Не повторяйте автоматически — результат не изменится.
404	Неизвестная модель / эндпоинт	Сверьте id со списком Моделей.
413	Слишком большое тело	Сожмите медиа или смените эндпоинт. Не повторяйте.
429	Лимит RPM/конкурентности	Повтор с экспоненциальной задержкой и джиттером.
502 / 503	Сбой источника / перегрузка шлюза	Повтор с задержкой; шлюз сам сначала пробует failover.

Пример экспоненциальной задержки

retry.py

import random
import time

from openai import OpenAI, APIStatusError

client = OpenAI(api_key="sk-sole-...", base_url="https://api.soleapi.com/v1")

RETRYABLE = {429, 502, 503}

def create_with_retry(**kwargs):
    delay = 1.0
    for attempt in range(5):
        try:
            return client.responses.create(**kwargs)
        except APIStatusError as e:
            if e.status_code not in RETRYABLE or attempt == 4:
                raise
            time.sleep(delay + random.random())  # jitter
            delay = min(delay * 2, 30)

Официальные SDK OpenAI и Anthropic сами повторяют 429/5xx (max_retries) — обычно этого достаточно. В своей реализации обязательно добавляйте джиттер, чтобы клиенты не повторяли запросы синхронно.

Советы по диагностике

Логируйте полное тело ошибки и время: поля type/status вместе с HTTP-статусом определяют категорию — см. Ошибки.
Единичные 5xx — нормальные флуктуации; разбирайтесь, только если они постоянны. Журнал запросов в консоли позволяет сверить каждый неудачный вызов.
При частых 429 сначала снизьте конкурентность, затем обсудите лимиты с администратором — см. Лимиты и квоты.