Ошибка Claude 529 Overloaded: как безопасно восстановить работу

529 overloaded_error означает временную перегрузку API Claude. Но сам код не говорит, где именно возникла проблема: в прямом API Anthropic, Claude Code, облачном провайдере или промежуточном шлюзе. Поэтому не запускайте бесконечные повторы сразу.

Сначала сохраните точный текст ошибки, время, модель, request_id, адрес API и сведения о частичном ответе. Затем определите провайдера, проверьте его статус и только после этого выполните ограниченный повтор с задержкой. Если до ошибки уже появился текст, завершился tool call или произошло внешнее действие, не отправляйте весь ход повторно вслепую.

Что сделать прямо сейчас

1. Остановите ручные и параллельные повторы. Клиент мог уже повторить запрос самостоятельно.
2. Сохраните контекст сбоя: HTTP-код, error.type, error.message, время с часовым поясом, модель, request_id, endpoint или base_url, версию клиента.
3. Проверьте результат: был ли частичный streaming-ответ, завершённый tool call, созданный файл, коммит, платёж, письмо или другое внешнее действие.
4. Установите фактический маршрут: Anthropic API, Claude Code через Anthropic, Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry либо собственный gateway.
5. Проверьте статус именно этого провайдера и компонента. Зелёная сводная страница сейчас не доказывает, что в момент вашего запроса не было краткого или регионального сбоя.
6. Разрешите один контролируемый повтор только если операция безопасна, а автоматические повторы уже учтены.

Это важнее советов вроде «смените VPN» или «нажимайте Retry, пока не заработает»: без данных о маршруте такие действия не устанавливают причину и могут добавить новые запросы к уже перегруженной системе.

Сначала убедитесь, что это действительно 529

В справочнике ошибок Claude API Anthropic разделяет 529 overloaded_error и 429 rate_limit_error. Похожие внешне сбои требуют разных действий.

Для 429 обычный rate limit может сопровождаться retry-after. Но лимит расходов может вести себя иначе, поэтому пауза сама по себе не всегда решает проблему. Проверяйте возвращённый тип, заголовки и панель того сервиса, через который действительно идёт запрос.

Определите, какой Claude у вас перегружен

Название «Claude» скрывает несколько разных путей. Найдите поверхность, на которой вы увидели ошибку, а затем — реального провайдера за ней.

Прямой Claude API

Признаки: ваш код обращается к api.anthropic.com, используется ключ Anthropic и официальный либо совместимый SDK. Здесь 529 соответствует определению Anthropic о временной перегрузке API.

Сохраните:

• request_id из тела ошибки или заголовок request ID;
• модель и endpoint;
• точное время;
• версию SDK и значение максимального числа повторов;
• число экземпляров приложения, которые могли повторять запрос одновременно.

Официальные SDK Anthropic по умолчанию повторяют некоторые временные ошибки, включая 5xx, с экспоненциальной задержкой два раза. Настройка зависит от SDK, языка, версии и конфигурации. Значит, до первого ручного Retry один логический вызов уже мог привести к трём отправкам: исходной и двум автоматическим.

Claude Code

Если Repeated 529 errors показал Claude Code, клиент уже выполнил применимые автоматические повторы. Текущая справка Claude Code описывает до десяти повторов для подходящих временных сбоев с экспоненциальной задержкой до показа ошибки.

В этом конкретном контексте repeated 529 не является usage limit и не учитывается в квоте Claude Code. Это утверждение нельзя переносить на денежные начисления прямого API или стороннего gateway.

Проверьте, какой provider настроен в Claude Code. Если это не Anthropic, публичный статус Claude не описывает весь ваш путь. Также посмотрите, был ли завершён текстовый блок или tool call: Claude Code намеренно не переигрывает некоторые mid-stream-сбои, чтобы не выполнить инструмент дважды.

claude.ai в браузере

Зафиксируйте время, видимую ошибку, название действия и состояние черновика. Не применяйте к веб-интерфейсу настройки SDK и не делайте вывод о причине по коду из расширения, reverse proxy или консоли браузера. Проверьте компонент claude.ai на официальной странице статуса, затем повторите действие после паузы, если оно не создавало внешний эффект.

Bedrock, Vertex AI, Microsoft Foundry или gateway

Если задан собственный base_url, облачная авторизация или совместимый endpoint, ответ мог быть создан либо преобразован посредником. Проверяйте статус облачного провайдера, регион, развертывание модели, квоты и логи gateway.

У такого маршрута может быть сразу несколько retry-слоёв:

text
приложение → SDK → gateway → облачный провайдер → модель

Каждый слой способен повторять запрос. Если приложение делает 3 попытки, SDK — ещё 3, а gateway — 2, один пользовательский вызов может породить гораздо больше upstream-запросов, чем ожидает разработчик.

Как повторять запрос без retry storm

Безопасная политика повтора состоит не из одной магической задержки, а из четырёх ограничений:

• один владелец повторов на уровне приложения;
• экспоненциальная задержка с небольшим случайным разбросом;
• жёсткий предел попыток и общего времени;
• остановка, если обнаружен частичный результат или побочный эффект.

Сначала выясните, сколько раз уже повторяет SDK или Claude Code. Если встроенный механизм достаточен, не оборачивайте его ещё одним агрессивным циклом. Если повтор контролирует ваше приложение, логика может выглядеть так:

ts
for (let attempt = 0; attempt < retryBudget; attempt++) {
  const result = await callClaude();

  if (result.ok) return result;
  if (result.hasPartialOutput || result.mayHaveSideEffect) break;
  if (result.status !== 529) throw result.error;

  await wait(backoffWithJitter(attempt));
}

throw new Error("Retry budget exhausted; preserve evidence and escalate");

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

Не включайте CLAUDE_CODE_RETRY_WATCHDOG=1 как случайное «исправление». В актуальной документации эта настройка заставляет unattended-сессии бесконечно повторять capacity errors 429 и 529, а для других временных ошибок поднимает стандартный предел до 300 попыток — примерно до трёх часов backoff. Такой режим требует заранее заданных ограничений конкурентности, бюджета, идемпотентности и внешнего stop-контроля.

Частичный ответ меняет решение

Ошибка может прийти внутри SSE-потока уже после начального HTTP 200. Поэтому проверяйте не только финальный статус, но и всё, что произошло до разрыва.

Перед повтором ответьте на четыре вопроса:

1. Получен ли завершённый текстовый блок, который можно сохранить?
2. Вернул ли Claude запрос на вызов инструмента?
3. Выполнил ли клиент этот tool call?
4. Изменил ли инструмент внешнее состояние?

К внешним эффектам относятся не только платежи. Это отправка письма, публикация, создание тикета, изменение базы, запуск deployment, запись файла, коммит или повторная постановка job в очередь.

Если эффект мог произойти, сначала сопоставьте локальный журнал, идентификатор операции и состояние внешней системы. Затем продолжайте с сохранённого результата либо повторяйте только доказанно невыполненный шаг. request_id помогает корреляции с поддержкой и логами, но сам по себе не доказывает завершение, отсутствие списания или идемпотентность.

Можно ли просто сменить модель

Иногда да: документация Claude Code указывает, что capacity отслеживается по модели, поэтому другая доступная модель может восстановить работу. Но это не универсальный первый шаг.

Перед переключением проверьте:

• доступна ли модель на вашем маршруте и в регионе;
• разрешена ли она политиками организации;
• подходит ли она по контексту, инструментам и качеству для текущей задачи;
• не будет ли переключение повторно запускать уже выполненный tool call;
• сохранён ли исходный запрос и частичный результат.

Для воспроизводимого процесса записывайте старую и новую модель в журнале. Тогда временный workaround не превратится в незаметное изменение поведения production-системы.

Что означает зелёный статус

Страница статуса — полезный сигнал, но не окончательный диагноз. Сопоставляйте:

• время ошибки и часовой пояс;
• компонент: Claude API, Claude Code или claude.ai;
• провайдера и регион;
• модель;
• длительность и частоту ошибок;
• успешность контрольного запроса после backoff.

Даже если агрегированный статус сейчас зелёный, ранее мог быть краткий сбой; проблема также может относиться к конкретной модели, региону, аккаунту или gateway. И наоборот, публичный инцидент не отменяет необходимость проверить, что ваш ответ действительно имеет код 529, а не 429 или сетевую ошибку.

Когда прекращать повторы и эскалировать

Остановитесь и соберите пакет диагностики, если:

• исчерпан заданный retry budget;
• 529 продолжается после паузы и единичного контрольного запроса;
• ошибка воспроизводится только на одной модели, в одном регионе или через один gateway;
• есть частичный ответ либо неопределённый внешний эффект;
• расход или число запросов растут неожиданно;
• request IDs заменяются или теряются на gateway;
• статус провайдера и ваши наблюдения противоречат друг другу.

Минимальный пакет для поддержки:

text
Время и часовой пояс:
Поверхность: API / Claude Code / claude.ai / другое
Provider и base URL:
Модель и регион:
HTTP status, error.type, error.message:
request_id и gateway request ID:
Версия SDK или Claude Code:
Настройки и фактическое число повторов:
Был ли partial output / tool call / внешний эффект:
Ссылка или снимок статуса на момент сбоя:

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

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

529 означает, что закончилась квота?

Для Claude API 529 overloaded_error означает временную перегрузку, тогда как лимиты обычно относятся к 429 rate_limit_error. В Claude Code displayed repeated 529 также не считается usage limit и не учитывается в квоте Claude Code. Но это не универсальное обещание об отсутствии денежных начислений в прямом API или стороннем gateway.

Сколько ждать перед повтором?

Универсального подтверждённого времени нет. Учитывайте встроенный backoff клиента, следуйте retry-after, если он применим и присутствует, добавляйте jitter и ограничивайте число попыток. После repeated 529 в Claude Code новый немедленный цикл обычно лишь дублирует уже выполненные повторы.

Тарифицируется ли запрос с 529?

Проверенные первичные справки не устанавливают одно правило для прямого API, timeout, mid-stream-сбоя и сторонних gateways. Сверьте usage records и биллинг именно вашего провайдера с request_id, временем и gateway-логами. Не делайте вывод только по HTTP-коду.

Поможет ли смена VPN или региона?

Не считайте это установленным исправлением. Сначала подтвердите сетевую проблему или региональную привязку маршрута. Иначе смена VPN добавит новую переменную, но не объяснит исходный 529.

Можно ли повторить тот же prompt?

Да, если не было частичного результата или побочного эффекта и retry budget это допускает. Если tool call уже мог выполниться, сначала проверьте внешнее состояние и продолжайте с безопасной точки, а не повторяйте весь ход.

Короткий алгоритм решения

529 + нет частичного результата + установлен провайдер: проверьте его статус, учтите автоматические повторы и выполните один ограниченный backoff-цикл.

529 + есть partial output или tool call: остановите повтор, сохраните вывод и проверьте побочные эффекты.

429: изучите retry-after, лимиты и spend cap; не применяйте диагноз 529.

Нет точного тела ошибки: соберите логи клиента, gateway и upstream, прежде чем менять модель, сеть или политику повторов.

Главная цель — не добиться случайного успешного ответа любой ценой, а восстановить работу так, чтобы один сбой не превратился в лавину запросов, двойное действие или неразрешимый спор о биллинге.