Claude API: ошибка 529 overloaded_error и настройка повторов

Ошибка 529 overloaded_error означает, что Claude API временно перегружен. Сообщение model overloaded в таком ответе говорит о нехватке мощности для обработки запроса, а не само по себе об исчерпанном личном лимите. Начните с проверки статуса сервиса, ограниченных повторов с увеличением паузы и уменьшения числа одновременных запросов. Сам код 529 не даёт оснований менять ключ или покупать другой план. Источник: ошибки Claude API.

Если SDK уже повторял вызов, не запускайте поверх него бесконечный цикл. Выберите, кто управляет повторами — SDK или приложение, — и заранее определите, когда запрос завершится неуспехом или будет отложен. Ниже есть настройка Python SDK и обработчик окончательного результата; они относятся к собственной API-интеграции. Для прерванной терминальной задачи используйте восстановление сессии Claude Code после 500 и 529.

Убедитесь, что сервер действительно вернул 529

Сохраните HTTP-код, error.type, время ошибки и адрес сервиса. Фраза «не удалось отправить сообщение» без ответа сервера ещё не устанавливает причину. Если приложение работает через шлюз, выясните, получен ли 529 от Anthropic или создан самим шлюзом.

Код 429 тоже требует внимательного чтения. В текущей документации он может означать ограничение скорости, месячный предел расходов уровня использования или предел расходов рабочего пространства Claude Code. Для 429 из-за месячного предела уровня использования заголовка retry-after нет, а повтор будет снова неуспешен до восстановления доступа. Поэтому правила «429 всегда содержит время ожидания» и «529 никогда его не содержит» для обработчика непригодны. Источник: таблица HTTP-ошибок.

Откройте Claude Status и проверьте компонент, относящийся к вашему запросу. Для облачного провайдера или шлюза нужна также его страница состояния либо журналы. Запишите время проверки. Зелёный статус — полезный сигнал, но восстановление конкретного вызова подтверждается его результатом. Если пока неясно, где возникла ошибка, начните с разбора ошибок в чате, Code, API и шлюзе.

Сколько повторов уже делает Python SDK

Официальный Python SDK по умолчанию выполняет два повтора временного сбоя с экспоненциальной задержкой. Это до трёх HTTP-попыток с учётом первоначальной, если все они разрешены политикой повторов. По умолчанию к повторяемым относятся ошибки соединения, 408, 409, 429 и статусы от 500, включая 529. Число меняется параметром max_retries; значение 0 отключает повторы SDK. Настройка доступна на клиенте и через with_options для отдельного вызова. Источник: повторы Python SDK.

Проверьте также очередь и шлюз. Если внешний цикл делает три вызова SDK, а каждый допускает два повтора, в худшем случае получается 3 × (1 + 2) = 9 HTTP-попыток ещё до дополнительных повторов шлюза. Это расчёт для заданных настроек, а не измерение реального трафика: успешный ответ или запрет повтора может остановить цепочку раньше.

Выберите одну из двух схем:

• Для простой интеграции оставьте ограниченные повторы SDK, а после окончательной ошибки верните результат приложению. Не добавляйте ещё один немедленный цикл.
• Если сроки и очередь контролирует приложение, отключите повторы SDK через max_retries=0. Тогда приложение само проверяет возможность повтора, допустимое время ожидания и оставшийся срок задачи.

Настройки Claude Code отличаются от SDK. Количество его автоматических повторов нельзя переносить в собственный API-клиент.

Настройка SDK и обработка окончательной ошибки

Для интеграции без инструментов можно использовать следующий фрагмент. Он принимает уже созданный anthropic.Anthropic, доступный вам идентификатор модели и список сообщений. Клиент должен быть настроен с вашими обычными учётными данными; ключи в код добавлять не нужно. Функция делает один вызов SDK с двумя разрешёнными повторами и возвращает результат, который вызывающая сторона обязана обработать.

import anthropic


def generate(client, model, messages):
    try:
        message = client.with_options(
            max_retries=2,
            timeout=20.0,
        ).messages.create(
            model=model,
            max_tokens=512,
            messages=messages,
        )
    except anthropic.APITimeoutError:
        return {"state": "timeout", "message": None}
    except anthropic.APIConnectionError:
        return {"state": "connection_error", "message": None}
    except anthropic.APIStatusError as error:
        if error.status_code != 529:
            raise
        return {
            "state": "overloaded",
            "message": None,
            "request_id": error.response.headers.get("request-id"),
            "retry_after": error.response.headers.get("retry-after"),
            "retry_after_ms": error.response.headers.get("retry-after-ms"),
        }
    return {
        "state": "complete",
        "message": message,
        "request_id": message._request_id,
    }

При complete передайте ответ пользователю. При overloaded закончите текущую попытку понятным сообщением: «Сервис временно перегружен; ответ не получен». Если у вас есть очередь, можно отдельно предложить отложить задачу и вернуть её идентификатор. Само значение overloaded ничего в очередь не помещает и не обещает, что задача выполнится позже. При timeout или connection_error направьте запрос в соответствующую диагностику; остальные HTTP-ошибки передаются общему обработчику через raise.

Проверка APIStatusError.status_code == 529 избегает зависимости от конкретного имени исключения. В исходном коде ветки main, проверенном 4 октября 2026 года, 529 уже получает отдельный OverloadedError, наследующий APIStatusError независимо от InternalServerError. Это состояние исходников, а не подтверждение наличия класса в любой установленной версии. Перед внедрением сверяйте свою версию SDK. Источники: отображение статусов, классы исключений.

Фрагмент проверен офлайн на подставных ответах: успешный результат, окончательный 529, другой HTTP-код, тайм-аут и ошибка соединения. Реальные запросы к модели и скорость восстановления сервиса не проверялись. Тест подтверждает переходы обработчика, а не внутреннюю работу установленного SDK.

Почему timeout не ограничивает всё время ожидания

timeout=20.0 в примере задаёт настройку тайм-аута запроса. Он не гарантирует, что функция завершится через 20 секунд: к времени обращения добавляются повторы и паузы между ними. По документации Python SDK тайм-аут по умолчанию составляет 10 минут, а APITimeoutError также повторяется дважды по умолчанию. Источник: тайм-ауты Python SDK.

Общий срок выполнения задачи учитывает ожидание в очереди, обращения к API, паузы и обработку результата. Для строгого срока приложению нужна отдельная отмена операции, поддерживаемая его средой выполнения. Проверка времени только перед вызовом не прерывает уже начавшийся запрос.

Если приложение само планирует повторы, перед каждой новой попыткой проверьте три условия: остались попытки, задача ещё нужна пользователю, а разрешённая пауза укладывается в её срок. Если до истечения срока осталось 25 секунд, а сервер просит ждать 30 секунд, завершите или отложите задачу. Нельзя сократить эту паузу до 25 секунд и затем отправить запрос раньше разрешённого времени.

В проверенном 4 октября 2026 года исходном коде Python SDK сначала читается retry-after-ms, затем retry-after в секундах или в виде HTTP-даты. Положительная задержка учитывается с техническим пределом платформенного ожидания, в том числе если она превышает 60 секунд. При отсутствии положительной задержки применяется экспоненциальная пауза со случайным разбросом. Там же явный x-should-retry: false запрещает повтор до проверки HTTP-кода. Наличие этих заголовков в каждом ответе не гарантируется; перед внедрением сверяйте поведение установленной версии. Источник: логика повторов SDK.

После последней разрешённой неудачи дополнительная пауза не нужна: следующего запроса уже не будет. Верните окончательный результат, чтобы интерфейс или очередь перестали ждать бесконечно.

Как снизить нагрузку и проверить восстановление

При всплеске 529 уменьшите число одновременных обращений к проблемному маршруту. Приостановите необязательные пакетные задания, ограничьте очередь и удаляйте из неё задачи с истёкшим сроком. Случайный разброс задержек помогает не отправлять все повторы в одну секунду. Это меры управления нагрузкой на стороне приложения, а не обещание устранить перегрузку Anthropic.

Для устойчивого сбоя можно временно приостановить новые обращения к этому маршруту — такой механизм обычно называют circuit breaker. Заранее задайте условие остановки, период проверки и способ возврата трафика. Не складывайте всё больше заданий в очередь без ограничения её размера и возраста: иначе после восстановления API пользователи получат давно ненужные ответы.

Проверяйте восстановление на разрешённом коротком запросе без чувствительных данных, сохранив модель, адрес API и способ доступа. Зафиксируйте HTTP-результат, длительность и идентификатор запроса. Успех означает, что этот запрос завершился; одного успешного обращения недостаточно, чтобы объявить восстановление всего сервиса. Возвращайте параллелизм постепенно и наблюдайте за долей 529, задержкой и возрастом очереди.

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

Что делать, если поток оборвался после HTTP 200

HTTP 200 подтверждает начало ответа, но не его полное завершение. В документации API прямо указано, что ошибка SSE может возникнуть после отправки этого статуса; обычной обработки неуспешного HTTP-кода тогда недостаточно. Источник: ошибки потоковых ответов.

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

Какие данные отправить в поддержку

Если тот же маршрут продолжает возвращать 529 после ограниченных повторов, сохраните компактный набор данных:

• время с часовым поясом, HTTP-код, error.type и сообщение ошибки;
• request_id из тела ответа и request-id из заголовка, если доступны;
• модель, адрес API, провайдера или шлюз и версию SDK;
• значения max_retries, тайм-аута и число дополнительных попыток приложения;
• полученные заголовки ожидания, параллелизм и итоговый результат задачи;
• состояние нужного компонента сервиса на момент проверки и обезличенный пример запроса.

Для прямого API идентификатор в теле ошибки и заголовке обычно совпадает; Python SDK предоставляет _request_id у успешного объекта ответа. У отдельных HTTP-попыток идентификаторы различаются. Поэтому храните также собственный ID задачи, связывающий её попытки. Шлюз может заменить или не передать идентификатор поставщика — в таком случае нужны его журналы. Источник: идентификаторы запросов API.

Удалите ключи, приватные сообщения и данные клиентов из отправляемого примера. Передавайте сведения оператору того сервиса, который вернул ошибку: ответ шлюза и ответ Anthropic могут потребовать разных обращений.

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

Что значит model overloaded в Claude?

В ответе API 529 overloaded_error это означает временную перегрузку. Сам текст model overloaded без HTTP-кода и сведений о сервисе не позволяет точно определить источник сбоя. Сначала сохраните полный ответ и выясните, используется ли прямой API, Claude Code или шлюз. Источник: ошибки API.

Поможет ли увеличение max_retries?

Оно разрешит больше попыток, но не создаст дополнительную мощность. Python SDK уже выполняет два повтора по умолчанию. Увеличивать число стоит только вместе с допустимым сроком задачи и контролем очереди; для быстрого интерфейса понятная окончательная ошибка может быть полезнее долгого ожидания. Источник: настройка повторов.

Через сколько минут исчезнет 529?

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

Нужно ли менять API-ключ при 529?

Из одного 529 такая необходимость не следует: он обозначает перегрузку. Проблемы ключа, доступа и оплаты проверяются по соответствующим кодам и сообщениям — например, 401, 403 или 402. Источник: значения HTTP-кодов.