Ошибки, лимиты частоты и надёжность
Продакшен-код общается с сетевым сервисом, поэтому он должен ожидать сбоев. Немного структуры здесь — это разница между ненадёжной интеграцией и надёжной.
Карта ошибок
Типичные HTTP-статусы, которые вам придётся обрабатывать:
| Статус | Значение | Что делать |
|---|---|---|
| 400 | Некорректный запрос | Исправьте полезную нагрузку; не повторяйте как есть |
| 401 | Неверный/отсутствующий API-ключ | Проверьте учётные данные |
| 403 | Не разрешено | Проверьте доступ/разрешения |
| 429 | Превышен лимит частоты | Сделайте задержку и повторите (соблюдайте retry-after) |
| 500/529 | Ошибка сервера / перегрузка | Повторите с задержкой |
SDK представляют их как типизированные исключения, так что вы можете чисто ветвиться, а не разбирать строки.
Повторы с задержкой
При временных ошибках (429, 5xx) повторяйте с экспоненциальной задержкой + джиттером, с ограничением:
import time, random
for attempt in range(5):
try:
return client.messages.create(...)
except (RateLimitError, APIStatusError) as e:
if attempt == 4 or not should_retry(e):
raise
time.sleep(min(2 ** attempt + random.random(), 30))
(Многие SDK повторяют временные ошибки автоматически — узнайте поведение вашего клиента по умолчанию, прежде чем добавлять собственное.)
Лимиты частоты
Лимиты применяются на уровне аккаунта/тарифа (запросы и токены в минуту). При достижении лимита вы получаете 429 с подсказками о таймингах. Стратегии: соблюдайте retry-after, сглаживайте всплески, выполняйте пакетно офлайн-работу и используйте более дешёвую модель (Выбор модели) для объёмных шагов.
Миграция моделей
ID моделей датированы/версионированы и со временем устаревают. Защитите себя:
- Читайте ID модели из конфигурации, а не из разбросанных литералов.
- Следите за устареваниями — см. Мониторинг устаревания и миграции и таблицу моделей.
- Перезапускайте свои оценки при смене моделей.