Rate limit в Claude Code: как отличить лимит подписки от API 429

Когда Claude Code выдаёт сообщение о rate limit, первый импульс — подождать или перезапустить. Но действие зависит от того, какой именно слой ограничивает запросы: подписка Claude.ai (Pro, Max, Team), Anthropic API или сторонний Endpoint. Эти три случая дают похожие симптомы, но требуют разных шагов.

Что означает rate limit в Claude Code

Claude Code может работать в двух принципиально разных режимах аутентификации:

• Подписка (Pro, Max, Team, Enterprise): вход через Claude.ai OAuth. Использование Claude Code и других поверхностей Claude расходуется из общего пула плана; текущие окна и дополнительные ограничения нужно смотреть в /usage и настройках аккаунта.
• API Key (ANTHROPIC_API_KEY в переменных окружения): запросы идут напрямую на api.anthropic.com. Ограничение может относиться к RPM/ITPM/OTPM, acceleration, usage tier spend cap или отдельному spend cap workspace. Точный случай определяют по текущему error body, headers и Anthropic Console.

Если в окружении выставлен ANTHROPIC_API_KEY, он имеет приоритет над подпиской. Claude Code переключится на API Key даже если вы вошли через подписку — это частый источник путаницы.

Нужно понять, дошёл ли запрос до стороннего Endpoint? При работе через BetterToken добавляется ещё один слой диагностики: в Dashboard можно проверить статус запроса, модель, input/output/cache Token и соответствующий расход. Это помогает отделить лимит провайдера от ошибки Anthropic API. Для настройки Base URL и API Key откройте документацию BetterToken и сверяйте конфигурацию с текущим workflow.

Как определить: подписка, Anthropic API или другой Endpoint

Первый шаг в любом случае — запустить /status внутри Claude Code. Команда покажет текущий метод аутентификации: subscription account или API Key. Именно это определяет, в какую сторону смотреть дальше.

• Подписка Pro/Max/Team: /status показывает subscription, а сообщение говорит о session или weekly limit и времени сброса. Ограничен usage плана. Сначала дождитесь сброса и проверьте /usage, а при наличии — /usage-credits.
• Anthropic API 429: /status показывает API Key, а ответ содержит HTTP 429 или rate_limit_error. Проверьте retry-after, текущее тело ошибки и rate/spend limits в Anthropic Console: одинаковый status может означать разные ограничения, а точные поля ответа зависят от Endpoint и версии API.
• Сторонний Endpoint: используется кастомный Base URL и ключ провайдера; код и формат ответа могут отличаться от Anthropic. Ограничена квота конкретного провайдера. Сначала прочитайте ответ, проверьте его status page и условия квоты.

Отдельно обрабатывайте 500 api_error, 504 timeout_error и 529 overloaded_error. Это серверные или временные ошибки, а не доказательство исчерпанной подписки. Для них нужен ограниченный exponential backoff. Каждый ответ Anthropic содержит request-id в заголовке, а ошибка — также request_id в JSON; сохраните этот идентификатор для поддержки.

429 и 529: разные области отказа

Признак	429 rate_limit_error	529 overloaded_error
Что ограничено	Rate, acceleration либо spend cap аккаунта или workspace	Сервис временно перегружен сразу для множества пользователей
Первый сигнал	HTTP 429, error body и rate-limit headers; retry-after есть не во всех вариантах	HTTP 529 и overloaded_error
Первое действие	Если есть retry-after, подождать; иначе классифицировать error code и проверить rate/spend limits	Ограничить очередь, применить exponential backoff с jitter и проверить status page
Что сохранить	Время, Model ID, безопасные rate-limit headers и request-id	Время, Model ID, номер попытки и request-id

Оба случая допускают только конечное число повторов. Если очередь продолжает расти, новые задачи нужно отклонить или отложить, а не создавать бесконечный retry loop. Отсутствие retry-after само по себе не доказывает нулевой баланс: классифицируйте ошибку по status, error.type, дополнительному коду и правилам конкретного endpoint.

Пошаговая диагностика без утечки API Key

Шаг 1. Проверить метод аутентификации

В сессии Claude Code:

/status

Обратите внимание на поле «Login method» или «Auth token». Если присутствует ANTHROPIC_API_KEY в окружении и вы хотите работать через подписку — сначала уберите переменную:

unset ANTHROPIC_API_KEY

После этого перезапустите и снова проверьте /status.

Шаг 2. Прочитать полный текст ошибки

Точный текст ошибки — главный диагностический сигнал:

• «Resets at [время]» → подписочный лимит, ждать сброса
• rate_limit_error + retry-after в заголовке → API rate limit, подождать указанный срок и смотреть в Anthropic Console
• rate_limit_error без retry-after → прочитать текущее тело ошибки и проверить spend cap в Anthropic Console; не считать это автоматически обычным RPM/TPM limit, потому что точные поля ответа могут различаться
• api_error, timeout_error или overloaded_error → временная 5xx/529 ошибка, повторять с backoff
• Ошибка со своим форматом + нестандартный Base URL → проблема на стороне провайдера

Вместе с кодом сохраните безопасный диагностический набор: время, error.type, request-id/request_id, версию Claude Code и выбранный Endpoint. Не прикладывайте API Key, заголовок Authorization или содержимое .env.

Шаг 3. Проверить текущее использование

Для подписки:

/usage

Текущий /usage показывает доступные для этого account/plan сведения: session token statistics для API-пользователей, plan usage, activity или credits — в зависимости от способа входа и версии. Используйте подписи и период именно своего экрана; не переносите фиксированные окна из старого туториала.

Для API откройте Anthropic Console и проверьте текущие rate limits, usage tier и применимые spend limits. Название раздела и доступные поля зависят от типа аккаунта и могут меняться.

Для BetterToken откройте Dashboard и найдите запрос по времени. Там можно проверить модель, статус, input/output/cache Token и расход. Dashboard помогает понять, дошёл ли запрос до BetterToken, но идентификатор из тела или заголовка ответа всё равно стоит сохранить отдельно.

Шаг 4. Проверить официальный статус

https://status.anthropic.com/

Если на статус-странице есть инцидент по Claude Code или API — это объясняет проблему вне зависимости от ваших лимитов.

Шаг 5. Проверить конфликт конфигураций

Ситуация, когда одновременно выставлены ANTHROPIC_API_KEY и ANTHROPIC_BASE_URL, может дать непредсказуемое поведение. Два набора переменных для разных схем аутентификации не должны существовать одновременно в одном окружении.

При запросе помощи по ошибке — никогда не включайте в логи или скриншоты значение Authorization заголовка, x-api-key или содержимое .env файла. Достаточно текста ошибки, HTTP-кода, версии claude --version и вывода /status (без значений ключей).

Что делать после определения источника лимита

Подписочный лимит (Pro/Max/Team):

• Подождать сброс окна — время показывает /usage и текст ошибки.
• Если сообщение относится к лимиту конкретной модели, выбрать доступную модель через /model; это не сбрасывает общий usage плана.
• Если есть usage credits — запустить /usage-credits и проверить настройки.
• Между несвязанными задачами использовать /clear — это сбрасывает контекст и снижает расход на следующих запросах.

Anthropic API 429 (rate_limit_error):

• Если есть retry-after, подождать указанное время; более ранний повтор не поможет.
• Если header отсутствует, прочитать текущее тело ошибки и проверить spend limits в Anthropic Console. Например, enforced spend cap требует изменения лимита или ожидания его сброса, а не backoff; не привязывайте обработчик к одному необязательному полю ответа.
• Для обычного rate или acceleration limit снизить параллелизм и наращивать нагрузку постепенно.
• Проверить текущий usage tier, rate и spend limits в Anthropic Console, не опираясь на старые фиксированные цифры.

Сторонний Endpoint:

• Открыть статус-страницу провайдера.
• Уточнить у провайдера текущую квоту и формат ошибки.
• При необходимости переключиться на прямой Anthropic API или другой провайдер.

5xx / 529:

• Для 500, 504 и 529 использовать ограниченный exponential backoff; официальный SDK уже повторяет часть временных ошибок.
• Проверить status.anthropic.com на наличие инцидента.
• Если ошибка сохраняется, передать поддержке request-id, время и тип ошибки, но не секреты.

Когда ждать, менять нагрузку или обращаться в поддержку

• Подписочный лимит со временем сброса: ждать, переключить модель или использовать /clear.
• API 429 с retry-after: ждать указанный период и снизить параллелизм.
• API 429 без retry-after: проверить error details и spend cap; действие зависит от конкретного кода.
• 500 / 504 / 529: применить ограниченный exponential backoff, проверить status сервиса и сохранить request-id.
• Ошибка стороннего Endpoint: обратиться к его провайдеру.
• Непонятный лимит при активной подписке: написать в поддержку claude.ai.
• Непонятный лимит при активном API Key: написать в поддержку Anthropic Console.

Подписочная поддержка и API-поддержка — разные команды. Лимит подписки Pro/Max не решит команда Anthropic API Console, и наоборот.

FAQ

Почему я вижу «rate limit», хотя только что начал сессию?

Возможные причины: (1) В окружении выставлен ANTHROPIC_API_KEY с низким tier, который имеет приоритет над подпиской. Проверьте через /status. (2) Предыдущая сессия израсходовала большой кусок rolling-окна — оно не сбрасывается при перезапуске Claude Code. (3) Если несколько устройств или агентных задач используют один аккаунт, лимиты суммируются.

Поможет ли смена модели через /model?

Только если текущий интерфейс прямо предлагает доступную модель и показывает отдельное ограничение. Переключение модели не следует считать универсальным способом сбросить plan usage: проверьте актуальный /usage, текст ошибки и правила своего плана.

Нужно ли включать полные логи, когда прошу помощь по ошибке?

Нет. Для диагностики достаточно: полный текст ошибки, HTTP-код, вывод /status без значений ключей, версия claude --version, время возникновения и состояние status.anthropic.com в этот момент.

Какие динамические лимиты меняются чаще всего?

Лимиты API по tier (RPM, ITPM, OTPM) и параметры подписочных окон могут меняться. Актуальные значения — только из официальных страниц:

• Costs и usage: code.claude.com/docs/en/costs
• API errors и rate limits: platform.claude.com/docs/en/api/errors
• Статус сервисов: status.anthropic.com

Не доверяйте числам из туториалов или форумов — они быстро устаревают.