Ошибки и повторы: 429, 529 и таймауты

В продакшене запросы иногда падают — это нормально. Важно различать ошибки, которые надо чинить (повтор не поможет), и ошибки, которые надо переждать и повторить.

Карта кодов

• 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(). Поток держит соединение живым, пока модель пишет.