Ошибки Claude Code и что с ними делать

Почти все ошибки Claude Code делятся на шесть семейств: лимиты, вход, контекст, сеть, сторона сервера и собственные настройки. Текст ошибки почти всегда называет семейство прямо, и дальше решение находится за один-два шага. Ниже - разбор по семействам с точными формулировками, чтобы можно было искать по строке из своей консоли.

Ошибки самой установки - отдельная тема, они разобраны в статьях про установку Claude Code и установку на Windows. Здесь про то, что ломается в работе.

С чего начинать в любом случае

Три команды, которые экономят время до того, как вы начали гадать.

Важное правило про сообщения об ошибках: часть из них означает, что ответ пришёл неполным, а не что запрос провалился. Формулировки «Server error mid-response» и «Connection lost mid-response» - как раз про это. Начинать заново не надо, достаточно написать в тот же диалог continue: агент помнит контекст и продолжит с места обрыва. Это же работает и в других сценариях обрыва ответа, и это самая часто пропускаемая мелочь во всём списке.

Лимиты, кредиты и 429

Самое частое семейство у тех, кто работает по подписке.

«You've hit your session / weekly / Opus / Sonnet limit» - израсходован лимит соответствующего окна. Лечится ожиданием сброса; какие именно окна бывают и как их не выбирать за час, разобрано в статье про лимиты Claude Code. Быстрое смягчение - переключиться на более лёгкую модель командой /model: лимиты у моделей считаются отдельно.

«Request rejected (429)» и «Server is temporarily limiting requests» - ограничение частоты запросов либо упор в лимит трат. Первое проходит само через несколько минут, второе требует проверить лимит расходов в аккаунте.

«Credit balance is too low» и «spend limit reached» - это уже про оплату по API, а не про подписку. Разница между этими двумя способами платить и когда какой выгоднее - в статьях про цену и работу через API.

«Usage credits required for 1M context» - расширенное контекстное окно доступно не на всех условиях и требует кредитов.

«Agent terminated early due to an API error» - агент оборвался на середине из-за ошибки API. Стоит посмотреть, что было причиной: перегрузка, лимит или аутентификация. Если это подагент, перезапускать его с нуля обычно не нужно - контекст сессии сохраняется.

Вход, ключи и 401

«Not logged in · Please run /login», «Login expired», «OAuth token refresh failed» - все три лечатся одинаково: /login заново.

«Invalid API key» и «API Error: 401 Invalid authentication credentials» - ключ неверный или отозван. Проверьте, какой ключ реально используется: переменная окружения ANTHROPIC_API_KEY перебивает то, что вы настраивали в интерфейсе, и это классический источник путаницы.

«Could not resolve authentication method» - конфигурация аутентификации противоречива: например, одновременно заданы и ключ, и вход по подписке в несовместимом сочетании.

«Your apiKeyHelper script is failing» - скрипт, выдающий ключ, падает. Запустите его руками и посмотрите, что он печатает.

«This organization has been disabled», «Your organization has disabled API key authentication», «... disabled Claude subscription access» - это политика организации, а не ваша ошибка; решается только администратором.

Prompt is too long и всё про контекст

Второе по частоте семейство, и единственное, где виновата не инфраструктура, а способ работы.

«Prompt is too long» - разговор перерос контекстное окно. Лечится /compact (сжать историю) или /clear (начать заново). Если следом приходит «Prompt is too long · automatic compaction failed», сжимать уже нечего - помогает только /clear.

«Context limit reached» и «Context exceeds the ...-token limit by ... tokens» - слишком большим оказался один обмен, а не вся история. Обычно это чтение огромного файла или вывод команды на десятки тысяч строк.

«Error during compaction: Conversation too long» - не сработало само сжатие. Тот же /clear.

Что делать, чтобы это не повторялось каждый час:

• не давать агенту читать целиком то, из чего нужны две строки - просить искать, а не читать;
• выносить поиск по репозиторию в подагента: он вернёт вывод, а десятки прочитанных файлов останутся в его контексте, а не в вашем;
• держать CLAUDE.md коротким - он грузится в каждую сессию целиком;
• начинать новую задачу с /clear, а не продолжать вчерашний диалог.

Рядом стоят ошибки размера отдельных вложений: «Request too large» (весь запрос больше 32 МБ), «Image was too large», «PDF too large» и «PDF is password protected». Здесь всё буквально: уменьшить, сжать, снять пароль.

Сеть, прокси и сертификаты

«Unable to connect to API», «Connection refused», «Socket is closed» - агент не достучался до сервиса. Проверять по порядку: интернет, прокси, брандмауэр.

«SSL certificate verification failed» - почти всегда корпоративный прокси, который подменяет сертификаты. Штатное решение - подсунуть Node корневой сертификат вашей организации через переменную NODE_EXTRA_CA_CERTS. Отключать проверку сертификатов не надо ни при каких обстоятельствах.

«proxy refused the connection» - прокси есть, но не пропускает; смотреть его правила.

«Request timed out» - ответ не пришёл за отведённое время, по умолчанию это десять минут. На медленном канале помогает увеличить API_TIMEOUT_MS, но чаще правильнее разбить задачу на части.

«API Error: No response from API» - не пришли даже заголовки ответа. Типичная причина - прокси, который держит соединение. Порог первого байта настраивается переменной CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS.

«Streaming response ended before any complete data was received» - поток оборвался в начале. Обычно нестабильная сеть, помогает повтор.

Ошибки на стороне сервера

Это семейство отличается тем, что чинить у себя нечего.

«API Error: 500 Internal server error» - сбой на стороне сервиса. Смотреть страницу статуса и ждать.

«API Error: Repeated 529 Overloaded errors» - сервис перегружен. Кроме ожидания, помогает /model: загрузка у разных моделей разная, и переключение нередко проходит сразу.

«... is temporarily unavailable, so auto mode cannot determine the safety ...» - недоступна модель-классификатор, которая проверяет действия в автоматическом режиме прав. Пока она недоступна, работают задачи только на чтение либо другой режим прав.

«Auto mode could not evaluate this action and is blocking it for safety» - классификатор ответил непонятно, и действие заблокировано на всякий случай. Повторить; если повторяется - запустить с --debug.

Настройки, права и доверие к папке

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

Settings Error - файл настроек не разобрался целиком: обычно лишняя запятая или комментарий //, которых JSON не допускает. Settings Warning - не разобрались отдельные записи, остальное действует. Что именно отброшено, покажет claude doctor.

«Ignoring N permissions.allow entries ... workspace has not been trusted» - правила разрешений из файла проекта не применяются, пока папка не помечена доверенной. Это защита от того, что кто-то положит опасные разрешения в общий репозиторий. Команда - /trust-workspace.

«File is covered by a Read deny rule in your permission settings» - файл закрыт вашим же правилом. Частый случай: правило Read(./.env*), поставленное когда-то ради безопасности, а теперь мешающее агенту прочитать пример конфигурации.

«Error: Settings file exceeds the 2MiB limit» и «Agent descriptions are over the 15.0k-token limit» - конфигурация разрослась. Второе обычно означает, что подагентов и их описаний стало слишком много.

«this write left the memory index at MEMORY.md at ..., over its ... read limit» - индекс автопамяти перерос лимит чтения, и всё, что за ним, при следующем запуске просто не загрузится. Разбирается там же, где вся память проекта.

«Configuration error» при старте - не читается ~/.claude.json. Битый файл сохраняется в ~/.claude/backups/, там же лежат пять последних рабочих копий.

Установка, обновление и запуск

«Installation was killed before it could finish (exit code 137)» - не хватило памяти или места на диске. Код 137 всегда означает именно это, гадать не нужно.

«The connection dropped while downloading the update» и «Download timed out» - обрыв закачки обновления, лечится повтором.

«Could not locate the Claude CLI on PATH» - обычно это сообщение из расширения редактора: сам CLI не установлен или не виден в PATH того процесса, из которого запускается.

«The current directory no longer exists» - каталог, из которого запущена сессия, удалён или переименован. Бывает после переключения веток и после чистки worktree.

«This conversation is already open in another running Claude session» - тот же разговор открыт в другом окне. Один разговор в один момент времени открывает одна сессия.

«No conversation found with session ID» и «This session's saved conversation is no longer on disk» - расшифровка сессии удалена. Стоит помнить, что старые расшифровки чистятся автоматически, срок задаётся ключом cleanupPeriodDays.

Быстрая таблица

Последняя строка заслуживает отдельного слова, потому что это самая частая жалоба без сообщения об ошибке. «Стал тупее» почти всегда объясняется одним из трёх: модель переключилась (в том числе автоматически при упоре в лимит), контекст переполнен и полезное в нём утонуло, либо изменились настройки. Все три проверяются двумя командами за десять секунд.

Как ставить задачи так, чтобы ошибок этого рода было меньше, - в статьях про работу с Claude Code и формулировку задач.