Если Claude Code или запрос к Claude API возвращает API Error: Rate limit reached, не начинайте с нового ключа, покупки кредитов или агрессивного retry. Текст ошибки говорит только о блокировке запроса. Исправление зависит от активного пути: Claude Code, API key, provider, кредиты, выбранная модель, размер контекста или состояние сервиса.
| Где появилась ошибка | Что проверить первым | Возможный владелец проблемы | Следующее действие |
|---|---|---|---|
| Claude Code в терминале или редакторе | /status, аккаунт, план, активный ANTHROPIC_API_KEY | Лимит Claude Code, логин, API-key override, контекст модели | Не меняйте всё сразу; подтвердите путь, затем ждите окно, перелогиньтесь или осознанно перейдите на API |
| SDK, curl или серверный HTTP 429 | API key, organization, project, model, response headers, Console Limits | Лимит Anthropic API для ключа, проекта, модели или токенов | Повторяйте только при доказанном давлении запросов или токенов |
| Gateway, hosted app, cloud или provider | Provider dashboard, upstream body, provider request id | Квота provider, wrapper throttle, неверный project, upstream limit | Диагностируйте provider до прямых советов по Anthropic API |
| Console показывает кредиты, billing или spend cap | Credits, billing, usage, spend configuration | Финансирование или состояние аккаунта | Остановите retry до изменения состояния аккаунта |
| Ошибка только на одной модели или длинном контексте | Model, context length, token volume, concurrency, fallback model | Давление модели, token window или model family | Сократите контекст, ограничьте output, снизьте concurrency или протестируйте меньшую модель |
| Несколько путей падают одновременно | Claude Status, timestamp, request id, recent deploys | Инцидент или деградация сервиса | Сохраните доказательства и ждите, не устраивайте хаос с аккаунтами |
Правило остановки такое: retry полезен только если доказано давление requests или tokens и есть reset, header, Console signal или provider signal. Если доказательства указывают на credits, billing, wrong project, wrong key, Claude Code allowance, provider quota или status incident, тот же самый запрос не починит ситуацию.
Десятиминутный порядок восстановления
В первую минуту сохраните точную ошибку. Нужны HTTP status, error type, error code, request id, endpoint, model, timestamp и timezone. Для Claude Code сохраните терминальный текст и состояние /status; для SDK сохраните response body и headers; для provider сохраните provider request id и upstream body, если он передан.
Во второй шаг определите активный путь. Claude Code проверяется через /status, /model, usage и переменные окружения. Прямой API проверяется через фактически загруженный key, organization, project и endpoint. Provider проверяется в dashboard и logs. Не меняйте одновременно key, model, retry policy и provider, иначе успешный тест ничего не докажет.
Третий шаг — scope. Новый key из того же project не исправит project-level лимит. Меньшая модель не исправит billing. Retry loop не исправит Claude Code subscription window. Provider route не исправляется проверкой чужого Anthropic Console. Каждая ветка требует своего минимального доказательства.
Четвёртый шаг — один маленький тест. В Claude Code это короткая команда в той же сессии после /status. В API это один маленький запрос тем же key и model после чтения headers. В provider это маленький запрос через тот же provider плюс log view. Цель — доказать ветку, а не дождаться случайного успеха.
Как читать доказательства API-лимита
Документация Anthropic описывает API limits как динамические ограничения по request rate, input tokens и output tokens. Для Messages API важны RPM, ITPM и OTPM. Небольшое число длинных запросов может упереться в token limit, даже если request count выглядит низким.
Когда подтверждён API-key путь, live evidence важнее старой таблицы лимитов. Сначала смотрите response headers и retry-after, затем Console Limits, Usage, Billing и Rate Limits API. Не планируйте production budget по чужим RPM числам: они зависят от аккаунта, проекта, модели, tier и времени.
| Доказательство | Что оно значит | Первый безопасный ремонт |
|---|---|---|
| Headers или Console показывают request pressure | Слишком много запросов в активном окне | Exponential backoff с jitter, lower concurrency, очередь по tenant |
| Давление input или output tokens | Контекст или генерация слишком большие | Сократить контекст, ограничить output, разделить задачу, использовать caching где уместно |
| Падает только одна модель или family | Лимит model family или выбранной модели | Проверить меньшую модель, уменьшить нагрузку, дождаться reset |
Backoff не должен быть слепым. Если client видит retry-after, используйте его. Если нет, ограничьте число попыток и включите jitter. Бесконечный retry увеличивает failed traffic и маскирует истинную причину.
Разделите Claude Code и прямой API
Claude Code часто выглядит как API, но договор другой. Он может работать через subscription login, API-key override, team environment или provider credentials. Команда /status — самый быстрый способ понять, какой путь активен сейчас.
Если активен subscription login, проверьте usage, выбранную модель, размер контекста и число параллельных сессий. Длинная coding-сессия накапливает summaries, tool outputs и предыдущий context. /compact, новая сессия, меньшая модель или сокращение параллельности могут быть корректными тестами, но не универсальным объяснением.
Если активен API key, переходите к API-диагностике. Проверьте ANTHROPIC_API_KEY, shell profile, project env, CI variables и provider credentials. Разные терминалы могут использовать разные ключи. Console, на который смотрит разработчик, не всегда тот project, который реально использует приложение.
Не используйте извлечение token, OAuth-обходы или случайные proxy как исправление. Они ухудшают доказуемость маршрута, создают риск для secrets и могут нарушить ожидаемое поведение аккаунта. Поддерживаемые действия: ждать окно, снизить нагрузку, исправить логин или перейти на платный API путь, который вы готовы мониторить.
Кредиты, billing и принадлежность key
Проблемы credits и billing часто выглядят как rate limit, потому что запрос просто блокируется. Но retry не добавляет средства и не меняет spend cap. Если Console показывает billing friction, low credits или account-state issue, остановите запросы до исправления состояния.
Key принадлежит organization и project. Provider route может иметь отдельную квоту, billing и throttle. Записывайте безопасные идентификаторы: organization, project, provider, environment source и deployment. Не копируйте сам key или bearer token в тикеты.
Подписка Claude и API usage — разные контракты. Pro или Max могут влиять на supported Claude product usage и Claude Code login path, но не становятся API credit wallet. Перед покупкой credits докажите, что активная ветка действительно API funding или billing.
Provider, cloud и состояние сервиса
Bedrock, Vertex AI, gateway, hosted app и внутренний proxy могут добавлять свой project, quota, throttle, model mapping и error wrapping. Upstream Anthropic error body полезен, но не доказывает, что direct Anthropic account exhausted.
Задайте три вопроса: видит ли provider локальный quota или billing block; есть ли upstream Anthropic request id или только provider id; падает ли тот же маленький запрос direct Anthropic credentials. Ответы отделяют provider-owned проблему от direct API и application-level throttling.
Claude Status проверяется отдельно. Если ошибки резко выросли без deploy, затронули несколько environments или несколько пользователей, статус может объяснить, почему ждать лучше, чем менять аккаунты. Green status не доказывает здоровье вашего key, provider, project, model или Claude Code session.
Эскалация и профилактика
Полезный пакет для support короткий: timestamp с timezone, exact error body, HTTP status, request id, active path, model, endpoint, безопасные org/project identifiers, response headers, Console или provider limit state, Claude Status state и последние изменения. Secrets, bearer tokens, session tokens и private prompts туда не входят.
В production добавьте per-tenant queues, concurrency limits per model family, logs для route, project, model, request id и token counts. Для Claude Code команд фиксируйте, какая сессия subscription-authenticated, а какая API-key-authenticated. Для provider храните provider id и upstream id рядом, иначе инцидент невозможно воспроизвести.
Хороший результат — не обещание, что лимиты исчезнут. Хороший результат — через десять минут понятно, какой путь отказал, какие доказательства это подтверждают, безопасен ли retry и какой владелец должен изменить состояние.
Операционный чеклист для команды
Команде стоит держать один короткий checklist в incident template: active path, credential source, model and context, live limit evidence, retry decision, escalation packet. Если хотя бы одно поле пустое, вывод «это просто rate limit» преждевременен.
Для удалённых контейнеров и CI важно отдельно записывать environment source. Локальный терминал может показывать один /status, а production job использовать другой key или provider project. Без этого разделения команда тратит время на исправление не того пути.
Повторные инциденты стоит сверять по pattern, а не по одному сообщению. Если каждый раз ошибку создаёт длинный context, профилактика лежит в prompt compaction и output caps. Если каждый раз виноват provider quota, нужен provider dashboard alert. Если каждый раз путаются subscription и API key, нужен startup check, который печатает безопасный route summary без раскрытия secrets.
Retry decision лучше хранить как явное поле, а не как комментарий в чате. Значения могут быть простыми: allowed-short-backoff, stop-and-fix-owner, escalate-with-evidence. Первый вариант требует headers, reset window или Console/provider signal. Второй нужен для billing, credits, wrong project, wrong key, provider quota или status incident. Третий нужен, когда evidence неполная, но impact уже production-level.
В логах важно оставить route, project, model, request id, token counts и безопасный credential fingerprint, но не сам key. Такой формат помогает support и on-call видеть разницу между Claude Code session, direct API и provider path, не превращая incident report в место хранения secrets.
Часто задаваемые вопросы
Нужно ли сразу повторять запрос?
Нет, пока не доказано request или token pressure. Retry допустим, когда есть reset, header, Console или provider signal. Billing, credits, wrong project, wrong key, Claude Code allowance, provider quota и status incident требуют другого действия.
Почему Claude Code пишет limit, если у меня Max или Pro?
Claude Code может идти через subscription login или API key. Выполните /status и проверьте ANTHROPIC_API_KEY. Max не доказывает, что CLI не использует API-key путь.
Покупка API credits исправит Claude Code?
Только если активная ветка — API funding или billing. Credits не исправляют subscription window, wrong login, provider quota, long context pressure или platform incident.
Может ли длинный контекст вызвать ошибку?
Да, если проблема в token pressure, model family или Claude Code session shape. Но это надо доказать через model, context length, token volume, concurrency и тест меньшей модели.
Почему через provider ошибка есть, а напрямую нет?
Provider может иметь отдельный quota, project, billing, throttle или model mapping. Смотрите provider dashboard и logs. Если есть upstream request id, сохраните оба id.
Что отправить в support?
Timestamp, timezone, exact error body, HTTP status, request id, active path, model, endpoint, safe org/project identifiers, relevant headers, Console/provider state, status page state и recent changes. Не отправляйте secrets.
