Ошибки Claude API: 429, 529, 400, 500 – что значат

Ошибки Claude API делятся на три группы, и от группы зависит, повторять запрос или чинить. Допустим, ваш скрипт или бот днём работал, а вечером в логах пошли красные строки: сначала 529, потом 429. Первая значит, что API перегружен у всех сразу и ваш код тут ни при чём. Вторая значит, что вы упёрлись в лимит. Ниже разберём, что делать в каждом случае, и начнём с общей картины: ваша ошибка (запрос, ключ или оплата) повторами не лечится, лимит и сбой на стороне Anthropic обычно лечатся паузой.

Что вы увидите в ответе API?

Откройте любую из тех красных строк: API всегда отвечает ошибкой в JSON. На верхнем уровне там объект error с полями type и message, рядом поле request_id. Вот пример из документации:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Тот же идентификатор приходит в заголовке ответа request-id. Сохраняйте его в логах: если придётся писать в поддержку Anthropic, именно по нему они находят конкретный запрос. А в коде смотрите на error.type, не на текст сообщения. В документации прямо сказано, что значения внутри этих объектов могут расширяться, а новых типов ошибок может стать больше.

Какая ошибка что значит?

Когда в логах несколько разных кодов, удобнее всего сверяться с таблицей: в ней видно, что значит каждый код и что с ним делать.

Код	Тип (error.type)	Что значит	Что делать
400	invalid_request_error	Проблема с форматом или содержимым запроса. Тип используется и для других 4xx, которых нет в списке. Также приходит, когда достигнут заданный вами лимит расходов организации или рабочего пространства	Читайте message, исправляйте запрос. Повторять без изменений бессмысленно
401	authentication_error	Проблема с API-ключом: неверный формат, отозван, истёк	Проверьте ключ в Claude Console, создайте новый
402	billing_error	Проблема с оплатой или платёжными данными	Проверьте платёжные данные в Claude Console
403	permission_error	У ключа нет прав на этот ресурс	Проверьте доступ организации и настройки рабочего пространства (workspace) в Console
404	not_found_error	Ресурс не найден	Проверьте путь эндпоинта и ID в адресе запроса
409	conflict_error	Запрос конфликтует с текущим состоянием ресурса, например, его изменили одновременно	Устраните конфликт, затем повторите
413	request_too_large	Превышен максимальный размер запроса	Уменьшите запрос; лимиты – в таблице ниже
429	rate_limit_error	Достигнут лимит запросов или токенов, месячный потолок расходов уровня либо лимит рабочего пространства Claude Code	См. следующий раздел
500	api_error	Неожиданная внутренняя ошибка у Anthropic	Повторите с экспоненциальной паузой; если не проходит – в поддержку с request_id
504	timeout_error	Запрос не уложился во время обработки	Для долгих запросов используйте стриминг
529	overloaded_error	API временно перегружен	Подождите и повторите

Если вы отправляете файлы или большие пачки текста, обратите внимание на 413: она зависит от типа запроса. По документации максимум такой: Messages API – 32 МБ, подсчёт токенов – 32 МБ, Batch API – 256 МБ, Files API – 500 МБ. На прямом Claude API эту ошибку отдаёт Cloudflare ещё до того, как запрос доходит до серверов API.

Почему пришла 429 и что с ней делать?

Вернёмся к вечеру с красными логами. Код 429 и тип rate_limit_error скрывают несколько разных ситуаций, и лечатся они по-разному, так что сначала надо понять, какая из них ваша.

Обычный лимит скорости. Для Messages API лимиты считаются в запросах в минуту (RPM), входных токенах в минуту (ITPM) и выходных токенах в минуту (OTPM) для каждого класса моделей. В ответе 429 сказано, какой именно лимит превышен, и есть заголовок retry-after – через сколько секунд повторять. Загвоздка в том, что API использует алгоритм «ведра токенов»: ёмкость постоянно пополняется до максимума, а не сбрасывается по расписанию. Поэтому лимит в 60 запросов в минуту может применяться как один запрос в секунду, и короткий всплеск способен вызвать 429, даже если за минуту вы укладываетесь.

Чтобы не ловить такие всплески вслепую, смотрите остаток в заголовках ответа: anthropic-ratelimit-requests-remaining, anthropic-ratelimit-input-tokens-remaining, anthropic-ratelimit-output-tokens-remaining и парные -limit и -reset.

Ускорение нагрузки. Если вы запустили скрипт на всю очередь сразу, при резком росте использования можно получить 429 из-за «лимитов ускорения». Чтобы их избежать, наращивайте трафик постепенно и держите ровную нагрузку.

Месячный потолок расходов уровня. Это самый неприятный случай. Уровни Start, Build и Scale имеют месячный потолок расходов (по документации: $500, $1000 и $200 000 соответственно). Когда он достигнут, API приостанавливается до 00:00 UTC первого числа следующего месяца, если вы не запросили повышение. Ответ тот же 429 с типом rate_limit_error, но без заголовка retry-after, а в теле есть error.details.error_code со значением enforced_spend_limit_reached. Повторы, в том числе автоматические повторы SDK, будут падать, пока доступ не вернётся, и отличить эту ситуацию от обычного лимита можно как раз по этому полю.

Ваш собственный лимит расходов устроен иначе. Если вы упёрлись в лимит, который сами задали в Console (на организацию или рабочее пространство), API вернёт не 429, а 400 с типом invalid_request_error. Сообщение начинается словами «You have reached your specified API usage limits». Поднимите или уберите лимит, чтобы вернуть доступ раньше срока. Для рабочего пространства Claude Code лимит проверяется отдельно, и там возможен как раз 429 – с заголовком retry-after.

Практический порядок такой. При 429 сначала смотрите, есть ли retry-after. Есть – ждите это время. Нет, а в теле enforced_spend_limit_reached – повторять бесполезно, нужно смотреть уровень и расходы в Console. Подробнее про устройство тарифов и лимитов Claude Code – в статье «Лимиты Claude Code».

Что делать, если API перегружен (529)?

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

• Повторить запрос с паузой. Не бомбардируйте API без перерыва: каждый следующий повтор делайте с растущей задержкой (экспоненциальная пауза).
• Не путать с 429. Документация отдельно оговаривает: если у вашей организации резко вырос объём, вы можете получить 429 из-за лимитов ускорения, а 529 – это общая перегрузка.
• Проверить, не мид-стрим ли ошибка. При стриминге ошибка может прийти уже после ответа 200. Тогда в потоке событий (SSE) вы получите событие error, например: event: error, data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}. Стандартные механизмы обработки HTTP-кодов тут не сработают, потому что статус уже был 200, поэтому событие error нужно обрабатывать в коде отдельно.
• Следить за статусом. Если 529 идут долго, проверьте страницу статуса Claude (status.claude.com).

Что значат 500 и 504?

Если вместо перегрузки вы видите 500 или 504, причина тоже не в вашем запросе, но лечится она по-разному.

500 api_error – неожиданная внутренняя ошибка у Anthropic. Документация рекомендует повторить с экспоненциальной паузой, а если ошибка не уходит, написать в поддержку и приложить request_id.

504 timeout_error – запрос не успел обработаться. Для долгих запросов документация советует стриминговый Messages API или Message Batches API, особенно когда запрос идёт дольше 10 минут. Не ставьте большой max_tokens без стриминга: некоторые сети обрывают «молчащие» соединения через непредсказуемое время, и запрос может упасть или зависнуть, так и не получив ответа. SDK проверяет, что обычный (не стриминговый) запрос не должен занять более 10 минут, и выставляет сокетные опции для TCP keep-alive. Если события по мере поступления вам не нужны, SDK умеет потреблять поток за вас и вернуть готовый объект Message. В Python это client.messages.stream(...) и stream.get_final_message().

Почему 400 после смены модели?

Допустим, вы перешли на новую модель, и ровно с этого момента запросы, которые вчера работали, стали падать с 400. Это типичная история: у новых моделей меняются поддерживаемые параметры. Документация приводит такие случаи (на октябрь 2026), и по ним удобно сверяться:

• Prefill не поддерживается. Модели Claude 4.6 и новее не принимают «предзаполненное» последнее сообщение ассистента. Сообщение: This model does not support assistant message prefill. The conversation must end with a user message. Вместо префилла – структурированные выводы, инструкции в системном промпте или output_config.format.
• Блоки thinking нельзя менять. Если в последнем сообщении ассистента были блоки thinking или redacted_thinking, их нужно возвращать в API ровно такими, как пришли. Изменённые, переставленные, отфильтрованные или восстановленные вручную блоки дают 400. Если вы фильтруете блоки по типу перед повторной отправкой, оставляйте оба типа.
• Расширенное мышление убрано. На Claude 4.7 и новее thinking: {"type": "enabled"} возвращает 400; нужно использовать адаптивное мышление (thinking.type.adaptive) и output_config.effort. И наоборот, у моделей Claude 4.5 и старше adaptive не поддерживается.
• Мышление нельзя отключить. На ряде моделей (в документации перечислены, в том числе Claude Opus 5.5) thinking: {"type": "disabled"} даёт 400. На Claude Sonnet 5.5 вместо этого есть режим {"type": "between_tools"} – самый низкий уровень мышления без размышлений перед ответом. Он не сочетается с уровнями усилия xhigh и max, а менять уровень усилия посреди диалога нельзя: иначе будет 400.
• Принудительный вызов инструмента не поддерживается. Для Claude Opus 5.5 и Sonnet 5.5 (а также Fable 5.1 и Mythos 5.1) параметры tool_choice: {"type": "any"} и {"type": "tool", ...} возвращают 400. Допустимы auto (по умолчанию) и none.
• Тип инструмента не поддерживается моделью. Например, для computer use на Opus 5.5 и Sonnet 5.5 на Claude API нужен набор computer_toolset_20260801, а старый тип computer_20251124 даёт 400, в сообщении перечислены допустимые типы.
• Блок thinking больше не соответствует диалогу. На Claude Fable 5.1, Opus 5.5 и Sonnet 5.5 воспроизводимый блок мышления принимается, только пока системный промпт, инструменты и предыдущие сообщения не менялись. Держите историю «только на добавление».

Список моделей и их возможностей меняется, поэтому перед исправлением сверяйтесь с разделом «Common validation errors» на странице Errors. О самих моделях – в статье «Claude Sonnet 5.5: что нового».

Что повторит SDK, а что вам?

Хорошая новость: часть работы за вас уже делает официальный SDK. Он автоматически повторяет временные сбои: ошибки соединения, ограничения скорости и серверные ошибки 5xx, по умолчанию два раза, с экспоненциальной паузой и с учётом заголовка retry-after. В документации Python SDK уточнено, что по умолчанию повторяются также 408 и 409. Число повторов настраивается параметром max_retries:

import anthropic

client = anthropic.Anthropic(max_retries=5)  # по умолчанию 2

try:
    message = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Привет, Claude"}],
    )
except anthropic.RateLimitError:
    print("429: нужно подождать")
except anthropic.APIStatusError as e:
    print("Ошибка API:", e.status_code)
except anthropic.APIConnectionError:
    print("Сервер недоступен")

Чтобы ловить ошибки по типу, а не по тексту, пригодятся классы исключений Python SDK. По документации: 400 – BadRequestError, 401 – AuthenticationError, 403 – PermissionDeniedError, 404 – NotFoundError, 409 – ConflictError, 422 – UnprocessableEntityError, 429 – RateLimitError, от 500 – InternalServerError, проблемы с соединением – APIConnectionError. Документация советует ловить типизированные классы, а не искать подстроки в тексте сообщения, и обрабатывать более конкретные классы первыми.

Всё остальное остаётся на вашей стороне, и вот короткий список того, что в коде делаете именно вы:

• не повторять 400, 401, 402, 403, 404 без исправления причины;
• логировать request_id каждой ошибки (в Python SDK он доступен как свойство _request_id у объектов ответа);
• отдельно обработать событие error внутри потока;
• для долгих задач использовать стриминг или Message Batches API;
• наращивать нагрузку постепенно, а не скачком.

Что делать с оплатой из России?

Если в логах появилась 402, дело в платёжных данных в Claude Console, а для читателя из России тут есть отдельная сложность. Anthropic официально не работает в России: страна не входит в список поддерживаемых, российские карты не принимаются. Способы оплаты разобраны в статье «Как оплатить Claude и ChatGPT из России без зарубежной карты». О том, чем отличается работа через API от подписки, – в статье «Claude Code через API или подписка».

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

Что значит 529 overloaded_error?

API временно перегружен из-за высокого трафика у всех пользователей. Это не проблема вашего ключа или запроса. Повторите запрос через некоторое время с растущей паузой; если запрос потоковый, проверьте, что вы обрабатываете событие error внутри потока.

Чем 529 отличается от 429?

429 (rate_limit_error) связана с вашей организацией: превышен лимит запросов или токенов, месячный потолок уровня или лимит рабочего пространства Claude Code. 529 (overloaded_error) – общая перегрузка API. Исключение: при резком росте вашего трафика можно получить 429 из-за лимитов ускорения.

Почему повторы после 429 не помогают?

Возможно, вы упёрлись не в лимит скорости, а в месячный потолок расходов уровня. В этом случае ответ приходит без заголовка retry-after, а в теле – error_code: enforced_spend_limit_reached. Доступ вернётся в 00:00 UTC первого числа следующего месяца или после повышения уровня.

Сколько раз SDK повторяет запрос сам?

По умолчанию дважды, с экспоненциальной паузой и с учётом retry-after. Изменить это можно параметром max_retries в клиенте; значение 0 отключает повторы.

Что делать с 400 после смены модели?

Прочитайте error.message и сверьте с разделом «Common validation errors» на странице Errors. Чаще всего причина – параметры, которые новая модель не принимает: префилл ответа, thinking в старом формате, принудительный tool_choice или изменённые блоки мышления.

Зачем сохранять request_id?

Это идентификатор, по которому находят ваш запрос: он приходит в заголовке request-id и в поле request_id тела ошибки. По нему поддержка Anthropic находит ваш запрос, поэтому сохраняйте его в логах.

Как избежать 504 на длинных ответах?

Используйте стриминг Messages API или Message Batches API, не ставьте огромный max_tokens в обычном запросе. Если события по ходу вам не нужны, SDK может собрать поток в готовый ответ за вас.

Чем закончится вечер с красными логами?

Теперь ваши строки 529 и 429 читаются иначе. Если пришла 529, подождите и повторите с растущей паузой: виновата общая перегрузка, а не вы. Если 429, проверьте, есть ли retry-after: есть – ждите, нет – откройте Console и смотрите потолок расходов. Остальные коды в таблице подсказывают, где чинить: в запросе, ключе, оплате или доступах.

Остались оговорки. Все данные взяты из официальной документации Claude Platform (страницы «Errors», «Rate limits», «Streaming» и «Python SDK») по состоянию на октябрь 2026. Точные суммы месячных потолков смотрите на странице Rate limits. Название модели в примере кода взято из документации, а актуальный список ищите на странице моделей Claude Platform.