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

Курс: Claude API для разработчиков — https://zero2claude.ru/learn/api
Канонический URL: https://zero2claude.ru/learn/api/3-3-oshibki-i-povtory

Коды ошибок API: 429 и 529 безопасно повторять с backoff, а 400 нужно чинить руками. Как отличить одно от другого.

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

## Карта кодов

- **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. Лови типизированные исключения, а не текст ошибки:

```python
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 и повтори.