Обработка ошибок и ограничения частоты запросов
Научитесь обрабатывать распространённые ошибки API, включая исключения из-за ограничения частоты запросов, ошибки аутентификации и превышение времени ожидания, используя повторные попытки и экспоненциальную задержку.
«Обработка ошибок и ограничения частоты запросов» — бесплатный урок AI Engineering Academy на CoddyKit. Это урок 4 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения AI Engineering Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс AI Engineering Academy содержит 4 уроков всего.
Почему возникают ошибки API
При вызове API многое может пойти не так: перегрузка, недостаточная квота, сбой сети или неверный запрос. Если считать вызовы безошибочными, код неизбежно окажется хрупким — сначала изучите типы ошибок.
Обзор типов ошибок OpenAI
SDK вызывает определённые исключения, например RateLimitError и AuthenticationError. Повторять вызов имеет смысл только для временных ошибок, таких как превышение ограничения частоты или сбой сети; остальные сами не исчезнут.
Перехват ошибок с помощью Try-Except
Оберните каждый вызов в try-except и перехватывайте конкретные исключения, а не используйте пустой except. Так Вы сможете правильно реагировать на каждый сбой, не скрывая ошибки в коде. Код показывает, как это сделать.
import openai
client = openai.OpenAI()
try:
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Hello!'}]
)
print(response.choices[0].message.content)
except openai.AuthenticationError as e:
print('Bad API key. Check OPENAI_API_KEY environment variable.')
raise # do not retry
except openai.RateLimitError as e:
print('Rate limited. Back off and retry.')
except openai.APIConnectionError as e:
print('Network error:', e)
except openai.APIStatusError as e:
print('Server error', e.status_code, e.message)Понимание ограничений частоты
OpenAI одновременно применяет два ограничения частоты: число запросов в минуту (RPM) и число токенов в минуту (TPM). Один огромный запрос может исчерпать TPM за один вызов. В обоих случаях возвращается код 429.
Экспоненциальная задержка: правильная стратегия повторных попыток
Достигли ограничения частоты? Подождите и повторите запрос с экспоненциальной задержкой: 1 с, 2 с, 4 с — каждый раз увеличивая интервал вдвое. Добавьте небольшое случайное отклонение и максимальное число попыток, чтобы цикл никогда не выполнялся бесконечно. Посмотрите код.
import time
import random
import openai
client = openai.OpenAI()
def call_with_backoff(messages, max_retries=5):
for attempt in range(max_retries):
try:
return client.chat.completions.create(
model='gpt-4o-mini',
messages=messages
)
except openai.RateLimitError:
if attempt == max_retries - 1:
raise
wait = (2 ** attempt) + random.uniform(0, 1)
print(f'Rate limited. Waiting {wait:.1f}s (attempt {attempt+1})')
time.sleep(wait)
except (openai.APIConnectionError, openai.APIStatusError):
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt)Использование библиотеки tenacity
Не реализуйте повторные попытки вручную — библиотека tenacity делает это аккуратно. Добавьте к функции декоратор @retry, и библиотека сама обработает задержки, случайное отклонение и условия повторных попыток.
from tenacity import retry, wait_random_exponential, stop_after_attempt
import openai
client = openai.OpenAI()
@retry(
wait=wait_random_exponential(min=1, max=60),
stop=stop_after_attempt(6)
)
def completion_with_backoff(**kwargs):
return client.chat.completions.create(**kwargs)
response = completion_with_backoff(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Tell me a joke.'}]
)
print(response.choices[0].message.content)Настройка времени ожидания
Зависший запрос может навсегда остановить приложение, поэтому всегда задавайте время ожидания. SDK принимает время ожидания в секундах — на уровне клиента или отдельного вызова. Выбирайте значение с учётом ожидаемой длины ответа.
import openai
# Set a default timeout for all requests from this client
client = openai.OpenAI(timeout=30.0)
# Or override per request
try:
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Summarize the French Revolution.'}],
timeout=60.0
)
except openai.APITimeoutError:
print('Request timed out. Try a shorter prompt or increase timeout.')Обработка ошибок аутентификации
AuthenticationError (401) означает, что Ваш ключ неверен, просрочен или отозван — повторные попытки не помогут. Запишите ошибку в журнал, отправьте уведомление и немедленно завершите операцию, вместо того чтобы тратить доступное число повторов.
import os
import openai
api_key = os.environ.get('OPENAI_API_KEY')
if not api_key:
raise EnvironmentError(
'OPENAI_API_KEY not set. Export it before running.'
)
client = openai.OpenAI(api_key=api_key)
try:
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Hello'}]
)
except openai.AuthenticationError:
# Do NOT retry - the key itself is invalid
raise RuntimeError('Invalid API key. Check OPENAI_API_KEY.')Квота и ограничения частоты
Оба случая выглядят как RateLimitError, но различаются: ограничения частоты действуют поминутно и сбрасываются сами, а ограничения квоты — это лимиты расходов, для снятия которых нужны дополнительные средства.
Запись ошибок для отладки
В рабочей среде записывайте в журнал каждую ошибку вместе с контекстом: типом, моделью, параметрами, числом токенов, временем и идентификатором запроса. Именно этот идентификатор нужен службе поддержки OpenAI. Посмотрите код.
import logging
import openai
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
client = openai.OpenAI()
def safe_completion(model, messages):
try:
response = client.chat.completions.create(
model=model, messages=messages
)
return response
except openai.RateLimitError as e:
logger.warning(
'Rate limit hit',
extra={'model': model, 'error': str(e)}
)
raise
except openai.APIStatusError as e:
logger.error(
'API server error',
extra={
'status_code': e.status_code,
'request_id': e.request_id,
'model': model
}
)
raiseОбработка ошибок в рабочих приложениях
Надёжная стратегия для рабочей среды: немедленно завершать выполнение при неисправимых ошибках, повторять временные ошибки с задержкой и предоставлять корректные запасные варианты. Никогда не позволяйте одной ошибке API обрушить весь сервер.
Быстрая проверка
Проверьте, насколько хорошо Вы поняли концепции разработки ИИ из этого урока.
Итоги урока
Вы научились обрабатывать сбои: OpenAI вызывает определённые исключения, ограничения частоты требуют задержки со случайным отклонением, а ошибки аутентификации должны приводить к немедленному завершению. Далее — создание эффективных запросов.
Часто задаваемые вопросы
Урок «Обработка ошибок и ограничения частоты запросов» бесплатный?
Да — полный текст урока «Обработка ошибок и ограничения частоты запросов» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс AI Engineering Academy, подпишись на CoddyKit PRO. Курс AI Engineering Academy содержит 4 уроков всего.
Чему я научусь в уроке «Обработка ошибок и ограничения частоты запросов»?
Научитесь обрабатывать распространённые ошибки API, включая исключения из-за ограничения частоты запросов, ошибки аутентификации и превышение времени ожидания, используя повторные попытки и экспоненц… Ты практикуешь AI Engineering Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.
Нужен ли мне опыт, чтобы начать AI Engineering Academy?
Предыдущий опыт не требуется. AI Engineering Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 4 из 4.
Сколько времени занимает урок «Обработка ошибок и ограничения частоты запросов»?
Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.
Можно ли писать и запускать код в этом уроке AI Engineering Academy?
Да. Каждый урок AI Engineering Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.
Все уроки этого курса
- Настройка среды Python
- Конечная точка чатовых дополнений
- Управление поведением модели с помощью параметров
- Обработка ошибок и ограничения частоты запросов