Ошибки, лимиты частоты и надёжность
- Прочитайте карту HTTP-ошибок и знайте, какие статусы повторять, а какие исправлять
- Повторяйте временные ошибки с экспоненциальной задержкой и джиттером, с ограничением
- Обрабатывайте лимиты частоты с помощью retry-after, сглаживания, пакетной обработки и более дешёвых моделей
- Изолируйте свой код от устаревания и миграции моделей
Продакшен-код общается с сетевым сервисом, поэтому он должен ожидать сбоев. Немного структуры здесь — это разница между ненадёжной интеграцией и надёжной.
Карта ошибок
Типичные 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 с подсказками о таймингах. Стратегии, чтобы оставаться под потолком:
Guided walkthrough1 of 4
- Когда вы получаете 429, прочитайте подсказку о тайминге в ответе и подождите столько времени, прежде чем повторять.
- Распределяйте запросы во времени вместо того, чтобы отправлять их все сразу.
- Переносите объёмные неинтерактивные задачи в пакетную обработку.
- Направляйте объёмные шаги на более дешёвую модель — см. «Выбор модели».
См. Выбор модели для подбора правильной модели для объёмных шагов.
Миграция моделей
ID моделей датированы/версионированы и со временем устаревают. Защитите себя:
- Читайте ID модели из конфигурации, а не из разбросанных литералов.
- Следите за устареваниями — см. Мониторинг устаревания и миграции и таблицу моделей.
- Перезапускайте свои оценки при смене моделей.
- 400/401/403 — это ваша вина: исправьте запрос или учётные данные, не повторяйте вслепую. 429 и 500/529 повторяемы.
- Повторяйте временные ошибки с экспоненциальной задержкой + джиттером, с ограничением (например, min(2 ** attempt + random(), 30)).
- При 429: соблюдайте retry-after, сглаживайте всплески, выполняйте офлайн-работу пакетно и направляйте объёмные шаги на более дешёвую модель.
- Читайте ID моделей из конфигурации, следите за устареваниями и перезапускайте оценки при миграции моделей.