Ошибка 529 overloaded у Claude: что значит и как её пережить

Ошибка claude overloaded 529 пугает тем, что приходит внезапно и посреди работы: агент останавливается, скрипт падает. Хорошая новость — с вашим ключом и балансом всё в порядке, это перегрузка на стороне API. Ниже — что о ней говорит документация Anthropic, как повторять запрос, когда переключаться на резервную модель и как такая ситуация выглядит при работе через шлюз Zukko.

Что значит claude overloaded 529

В документации Anthropic код 529 с типом overloaded_error описан так: API временно перегружен. Там же уточняется, что 529 возникает при высоком трафике сразу у всех пользователей. Тело ошибки устроено так же, как у остальных ошибок API:

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "..."
  },
  "request_id": "req_..."
}

request_id пригодится, если будете писать в поддержку. В стриминге ошибка может прийти уже после ответа 200 — отдельным событием внутри потока, поэтому обрабатывайте ошибки и там.

Не путайте 529 с соседними кодами:

Одна оговорка из той же документации: при резком росте вашего трафика вы можете получить не 529, а 429 из-за ограничения на ускорение. Совет Anthropic — наращивать нагрузку постепенно.

В Claude Code эта ошибка выглядит как API Error: Repeated 529 Overloaded errors — она показывается после того, как Claude Code уже несколько раз повторил запрос сам. В документации Claude Code прямо сказано: 529 — не ваш лимит использования и в квоту не засчитывается.

Что делать: повтор с задержкой

Перегрузка обычно временная, поэтому первое средство — повторить запрос, но с умом:

1. Экспоненциальная пауза со случайной добавкой. 1, 2, 4 секунды плюс доли секунды случайно, чтобы ваши воркеры не били в API одновременно.
2. Заголовок retry-after. Если он пришёл, ждите не меньше указанного.
3. Ограниченное число попыток. Две-три на одной модели, дальше — резервная модель или ошибка наверх.
4. Не дублируйте повторы. Официальный Anthropic SDK уже повторяет временные ошибки, включая 5xx, два раза по умолчанию (параметр max_retries). Если пишете свой цикл, отключите встроенный, иначе попыток станет втрое больше. В Python SDK ошибка 529 приходит как исключение anthropic.OverloadedError.

В Claude Code число автоматических повторов задаёт переменная CLAUDE_CODE_MAX_RETRIES (по умолчанию 10).

Резервная модель

Если повторы не помогли, переключайтесь на другую модель. Документация Claude Code объясняет, почему это работает: мощности учитываются отдельно для каждой модели, и перегрузка одной не означает перегрузку другой.

Пример цепочки и её цена на 1 000 запросов по 2 000 входных и 500 выходных токенов (цены на 7 октября 2026, формула 1000 × (2000 × вход + 500 × выход) / 1 000 000):

Индекс силы — Intelligence Index от Artificial Analysis из каталога Zukko. Проверка строки: для Opus 5.5 — 2 × 0.8 + 0.5 × 4 = 1.6 + 2 = $3.60. Модель другого вендора в конце цепочки страхует от ситуации, когда проблемы у всего провайдера. Перед тем как ставить резерв в продакшен, прогоните на нём 20–30 типичных запросов: держит ли он формат ответа, который ждёт ваш код.

Две практические детали. У резервной модели свой кэш, поэтому первый запрос после переключения пройдёт без чтения кэша. А если на ключе настроены allowed_models, добавьте туда резервные модели, иначе вместо ответа получите 403. Актуальный список и цены — GET https://api.zukko.pro/v1/models или страница «Модели» в кабинете.

Резервная модель в Claude Code

В Claude Code есть флаг --fallback-model: при перегрузке или недоступности основной модели он переключает текущий ход на резервную. Можно указать до трёх моделей через запятую, а для постоянной настройки — массив fallbackModel в settings.json:

claude --fallback-model claude-sonnet-5

По документации переключение действует только на текущий ход, следующее сообщение снова идёт в основную модель. Ошибки авторизации, оплаты и rate limit резервную модель не включают. Вручную модель меняется командой /model. Настройка Claude Code с Zukko — в документации по Claude Code↗; не забудьте задать ANTHROPIC_DEFAULT_HAIKU_MODEL на модель из каталога, иначе фоновые запросы уйдут на claude-haiku-* и получат 404 model_not_found.

Как перегрузка выглядит через Zukko

При работе через шлюз перегрузка провайдера может прийти как 529 (шлюз пробрасывает статус провайдера) или как 503 — обрабатывайте оба одинаково. Коды, которые стоит различать:

Собственного общего rate limit у Zukko нет. Чтобы код был устойчивым при любом пути запроса, обрабатывайте 529 и 503 (без model_disabled) одинаково — как временную перегрузку. Подробнее о 503 — в статье о недоступном провайдере↗.

Код: повторы и резерв на Anthropic SDK

Через Zukko любую модель можно вызывать в любом формате, поэтому в цепочку на Anthropic SDK спокойно ставится и GPT — шлюз сам сконвертирует запрос:

import random
import time

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.zukko.pro",
    api_key="fetch_ваш_ключ",
    max_retries=0,  # повторами управляем сами
)

CHAIN = ["claude-opus-5-5", "claude-sonnet-5", "gpt-6.1-sol"]
RETRYABLE = {429, 500, 502, 503, 504, 529}
KEY_LIMITS = {"key_daily_limit_reached", "key_monthly_limit_reached"}

Код повторяет запрос только на временных ошибках, включая 529 и 503, а на лимите ключа, нехватке баланса и ошибках запроса сразу останавливается: их не исправит ни пауза, ни другая модель. Справка по эндпоинту — в документации /v1/messages↗, версия того же подхода на OpenAI SDK — в статье о повторах при 503↗.

Если хотите, чтобы резервные модели были доступны по тому же ключу без отдельных аккаунтов у каждого вендора, создайте ключ в кабинете и внесите цепочку в allowed_models.

Частые вопросы

529 — это мой лимит?

Нет. По документации Anthropic это перегрузка API у всех пользователей. Ваш лимит — это 429 rate_limit_error. Про похожую путаницу у OpenAI — в статье ошибка insufficient_quota↗.

Сколько ждать, если 529 не проходит?

Обычно перегрузка временная. Сделайте две-три попытки с растущей паузой, потом переключайтесь на резервную модель. Состояние сервиса Anthropic публикует на status.claude.com.

Почему через Zukko иногда приходит 503, а не 529?

Перегрузка провайдера через шлюз может прийти как 529 — шлюз пробрасывает статус провайдера — или как 503, которым Zukko сообщает о недоступности провайдера. Обрабатывайте 529 и 503 одинаково — как в коде выше — и ваш код будет работать при любом пути запроса.

Поможет ли смена модели?

Да, мощности учитываются для каждой модели отдельно. Самый надёжный резерв — модель другого вендора, проверенная заранее на ваших запросах.