В продакшене запросы иногда падают — это нормально. Важно различать ошибки, которые надо чинить (повтор не поможет), и ошибки, которые надо переждать и повторить.
Карта кодов
- 400 — плохой запрос: опечатка в параметре, неверный JSON, сообщения не чередуются user/assistant. Повтор бессмысленен — чини запрос.
- 401 — проблема с ключом: не задан или неверный
x-api-key. Чини конфиг (ключ живёт в переменной окружения, не в коде). - 429 — rate limit: слишком много запросов. Повторять можно — с задержкой (backoff). В ответе есть заголовок
retry-after. - 500 / 529 — перегрузка на стороне Anthropic. Повторять с backoff.
Правило простое: 429 и 5xx — ретраить с нарастающей паузой; 400 и 401 — не ретраить, исправлять.
SDK уже умеет ретраить
Официальный SDK сам повторяет 429 и 5xx с экспоненциальным backoff. Лови типизированные исключения, а не текст ошибки:
import anthropic
try:
resp = client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
messages=[{"role": "user", "content": "..."}],
)
except anthropic.BadRequestError:
raise # 400 — баг в запросе, чинить
except anthropic.RateLimitError:
pass # 429 — SDK уже ретраил; обработай очередь
except anthropic.APIError as e:
log(e.status) # прочее, в т.ч. 5xx
Про таймауты
Если просишь длинный ответ (большой max_tokens), обычный запрос может упасть по таймауту. Решение — стримить: client.messages.stream(...) + .get_final_message(). Поток держит соединение живым, пока модель пишет.
Заметка
stop_reason == «max_tokens» — это не ошибка, а сигнал: ответ оборвался, потому что упёрся в лимит. Подними max_tokens и повтори.
Практика в терминале
В тренажёре ниже сломай запрос нарочно: отправь его без заголовка x-api-key и рассмотри JSON ошибки аутентификации. Затем добавь ключ и повтори тот же запрос — почувствуй разницу между «чинить» и «ретраить».