Ошибки Claude Code: API Error 400, 401, 429, 529 и блокировки

Что означает «API Error» в Claude Code и с чего начать

Сообщение вида «API Error: 529» или «API Error: 400» означает одно: Claude Code отправил запрос к API модели, а сервер ответил HTTP-кодом ошибки. Число после двоеточия — это и есть код, и по нему сразу понятно, где искать причину. Коды 4xx почти всегда указывают на проблему на вашей стороне: неверный ключ, не та переменная окружения, слишком длинный контекст, неподдерживаемый параметр. Коды 5xx и 529 — проблема на стороне сервера: перегрузка или временный сбой, который обычно лечится ожиданием.

Если Claude Code не работает и непонятно почему, начните с трёх проверок. Команда claude doctor из обычного терминала показывает состояние установки, ошибки в файлах настроек и предупреждения с предложенными исправлениями — она работает, даже если сессия не запускается. Внутри сессии то же делает /doctor, а /status показывает, какой способ авторизации сейчас активен. Этого хватает, чтобы разобраться в большинстве случаев.

Ниже — таблица всех частых кодов, затем подробный разбор каждой группы, сетевые ошибки, проблемы установки, блокировки аккаунтов и отдельно ошибки, которые возвращает шлюз, если вы работаете через него.

# из обычного терминала: диагностика установки и настроек
claude doctor

# внутри сессии Claude Code
/doctor     # проверка установки, настроек и расширений
/status     # какой способ авторизации активен
/context    # сколько контекста уже занято

Таблица: код ошибки, причина и что делать

Сводка по кодам, которые встречаются в Claude Code чаще всего. Сообщения в самом интерфейсе бывают длиннее, но код в начале строки всегда совпадает с HTTP-статусом ответа.

API Error 400: что ломает запрос

Ошибка 400 значит, что сервер понял запрос, но отказался его выполнять: что-то в нём не соответствует правилам API. Самый полезный шаг — дочитать сообщение до конца, там почти всегда написано, какое именно поле не понравилось.

Первая группа причин — параметры, которые конкретная модель не поддерживает. У Claude Opus 5.5 и Claude Fable 5.1 мышление включено всегда: значение disabled в параметре thinking и старый параметр budget_tokens возвращают 400. У этих же моделей запрещён принудительный вызов инструмента — tool_choice со значениями any и tool тоже даёт 400. Сам Claude Code такие запросы не формирует, но если вы гоняете через тот же ключ свои скрипты или ставите на новую модель старое расширение, ошибка вылезет именно так. Подробный список ломающих изменений — в разборе миграции на Claude 5.

Вторая группа — повреждённая история диалога. Сообщения вроде «orphaned tool_result in conversation history», «duplicate tool_use ID» или ошибки в блоках мышления появляются после сбоя посреди ответа. Официальная рекомендация — начать новую сессию командой /clear.

Третья — контекст. «Prompt is too long» или «Context limit reached» означает, что история не помещается в окно модели. Сожмите её командой /compact, а если это не помогает — /clear. Если же ошибка говорит, что текущая версия Claude Code не поддерживает выбранную модель, обновите сам инструмент.

/compact                    # сжать историю, если контекст переполнен
/compact keep only the plan and the diff
/clear                      # начать с чистого листа при битой истории

# обновить Claude Code, если модель не поддерживается версией
claude update

Подробнее: Что ломается при переходе на Claude 5 · Как устроены контекст и токены в Claude Code

API Error 401, 403 и 404: ключ, доступ и адрес

401 — ошибка авторизации: ключ неверный, отозван, просрочен или просто лежит не там, где его ищет Claude Code. Классическая ситуация — в профиле оболочки остался старый ANTHROPIC_API_KEY от прошлого проекта, и он перебивает ваши текущие настройки. Команда /status внутри сессии показывает, какой способ авторизации активен на самом деле. Лишнюю переменную уберите и из текущего окна, и из ~/.zshrc, ~/.bashrc или профиля PowerShell.

Если вы подключаетесь не напрямую к Anthropic, а через провайдера, важно, в какую переменную положен ключ. Для нашего шлюза это ANTHROPIC_AUTH_TOKEN, а адрес задаётся в ANTHROPIC_BASE_URL. Опечатка в имени переменной не вызывает отдельной ошибки — Claude Code просто её не видит и отправляет запрос без нужного ключа.

403 означает «доступ запрещён». При установке это часто «App unavailable in region»: официальный установщик сообщает, что Claude Code недоступен в вашей стране. Также 403 возвращают корпоративные прокси, которые блокируют хост, и шлюзы, когда запрошенный маршрут не обслуживается.

404 почти всегда про адрес или модель. Либо в ANTHROPIC_BASE_URL опечатка или лишний сегмент пути, либо указан несуществующий идентификатор модели. Идентификаторы пишутся полностью и без дат: claude-opus-5-5, claude-sonnet-5, claude-fable-5-1, claude-haiku-4-5. Список моделей, доступных вашему ключу, можно получить запросом к /v1/models — через наш шлюз этот запрос не тарифицируется.

# macOS / Linux: убрать мешающий ключ и проверить переменные
unset ANTHROPIC_API_KEY
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

# Windows PowerShell
Remove-Item Env:ANTHROPIC_API_KEY
$env:ANTHROPIC_BASE_URL

# проверить ключ и список моделей через шлюз (токены не списываются)
curl -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" https://claude-gateway.ru/api/v1/models

Подробнее: Как подключить Claude Code по API-ключу · Переменные окружения в документации

API Error 529, 500 и 429: перегрузка и лимиты

529 Overloaded — самая частая ошибка у тех, кто ищет «api error 529 claude». Она означает, что серверы модели перегружены прямо сейчас. Ваш запрос корректен, ключ в порядке, делать с настройками ничего не нужно. Claude Code сам повторяет такие запросы с увеличивающейся паузой, и сообщение «Repeated 529 Overloaded errors» появляется, только когда повторы не помогли. Вариации того же — «Opus is experiencing high load» и «Fable is experiencing high load».

Лучшая защита от 529 — запасная модель. Флаг --fallback-model принимает список через запятую: если основная модель перегружена, недоступна или вернула другую неповторяемую серверную ошибку, Claude Code переключится на следующую и покажет уведомление. Постоянную цепочку можно прописать в settings.json в поле fallbackModel.

500 Internal server error — внутренний сбой API. Лечится повтором, и Claude Code делает его автоматически. Если ошибки 500 идут потоком, подождите несколько минут. Число повторов настраивается переменной CLAUDE_CODE_MAX_RETRIES.

429 — превышен лимит. У подписки это сообщения вроде «You've hit your session limit» или «You've hit your weekly limit»: остаётся ждать сброса окна. При работе через API это лимит запросов или исчерпанный баланс. У нашего шлюза есть свой 429 — на число одновременных запросов, о нём ниже.

# запасные модели на одну сессию
claude --fallback-model sonnet,haiku

# постоянно — в ~/.claude/settings.json
{
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}

Подробнее: Какую модель ставить основной, а какую запасной

Сетевые ошибки: прокси, сертификаты, таймауты

Если Claude Code не может достучаться до API, вы увидите «Unable to connect to API», «Connection refused», «Can't reach the API server» или «Couldn't connect through your proxy». Сначала проверьте, что адрес вообще доступен из вашей сети, затем — настройки прокси. Claude Code читает стандартные переменные HTTPS_PROXY и HTTP_PROXY.

Ошибки «SSL certificate verification failed» и «unable to get local issuer certificate» типичны для корпоративных сетей, где прокси подменяет сертификаты. Правильное решение — указать корпоративный корневой сертификат через NODE_EXTRA_CA_CERTS. Совет «поставьте NODE_TLS_REJECT_UNAUTHORIZED=0» из форумов отключает проверку сертификатов целиком; официальная документация допускает это только для разработки, для рабочей машины так делать не стоит.

«Request timed out» появляется, когда ответ идёт слишком долго. Длинные ответы на высоком уровне усилия действительно могут занимать минуты. Таймаут настраивается переменной API_TIMEOUT_MS в миллисекундах. Обрывы посреди ответа — «Connection lost mid-response», «Response stalled mid-stream» — чаще всего означают нестабильную сеть; Claude Code повторяет такие запросы сам.

# прокси (macOS / Linux)
export HTTPS_PROXY=http://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080

# корпоративный корневой сертификат
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

# увеличить таймаут запроса до 10 минут
export API_TIMEOUT_MS=600000

# Windows PowerShell
$env:NODE_EXTRA_CA_CERTS = 'C:\path\to\corporate-ca.pem'

Ошибки установки: command not found, PATH и Node.js

«command not found: claude» или «'claude' is not recognized» после установки означает, что папки с программой нет в PATH. Нативный установщик кладёт claude в ~/.local/bin на macOS и Linux и в %USERPROFILE%\.local\bin на Windows. Добавьте эту папку в PATH и откройте новое окно терминала: сессия, в которой шла установка, помнит старый PATH.

Если вы ставите через npm, проверьте версию Node.js. По официальной документации npm-пакет начиная с версии 2.1.198 требует Node.js 22 или новее; на старой версии npm выдаёт предупреждение EBADENGINE, но установка обычно завершается. Не используйте sudo npm install -g — это источник проблем с правами.

На Windows при установке через npm бывает «running scripts is disabled on this system»: политика выполнения PowerShell блокирует скрипты-обёртки npm. Решения — разрешить локальные скрипты для текущего пользователя или вызывать claude.cmd. И наконец, если после обновления запускается старая версия, у вас, скорее всего, две установки сразу — нативная и через npm. Оставьте одну.

# проверить установку
claude --version
node --version

# macOS / Linux: добавить папку в PATH (zsh)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

# установка через npm
npm install -g @anthropic-ai/claude-code

# Windows: разрешить скрипты npm для текущего пользователя
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Подробнее: Пошаговая установка на Windows, macOS и Linux

Claude Code заблокирован: почему банят аккаунты и что делать

Запросы «claude code забанили» и «блокировка claude code» почти всегда про одну ситуацию: аккаунт Claude, через который работал инструмент, заблокирован. В Claude Code это выглядит как «Your account is on hold and can't use Claude Code» или «This organization has been disabled».

Причина для пользователей из России в большинстве случаев одна и та же. Anthropic официально работает только в странах из своего списка поддерживаемых, России в нём нет. Аккаунты, зарегистрированные или используемые из неподдерживаемого региона, оплаченные через посредников чужими картами или купленные готовыми, нарушают условия сервиса, и Anthropic их блокирует. Вместе с аккаунтом пропадает оплаченная подписка, а агент встаёт посреди задачи.

Что делать с уже заблокированным аккаунтом. В сообщении Claude Code указан адрес claude.ai/restricted, где можно посмотреть детали и подать апелляцию. Шансы есть, если блокировка ошибочная. Если же аккаунт нарушал правила по региону или оплате, обходить блокировку новыми аккаунтами бессмысленно: следующий ждёт то же самое.

Легальная альтернатива — работать с моделями не через личный аккаунт claude.ai, а по API через провайдера, который обслуживает клиентов в России и сам отвечает за доступ к моделям. Claude Code официально поддерживает смену адреса API через ANTHROPIC_BASE_URL, поэтому это штатный режим работы, а не хак. Через наш шлюз, например, вы оплачиваете тариф в рублях, получаете собственный ключ и можете в любой момент отозвать и перевыпустить его. Шлюз — независимый сервис, не связанный с Anthropic, это стоит понимать при выборе.

• Не покупайте готовые аккаунты Claude: их блокируют вместе с балансом.
• При ошибочной блокировке — апелляция через claude.ai/restricted.
• Для постоянной работы из России — доступ по API через провайдера с оплатой в рублях.
• Ключ провайдера кладётся в ANTHROPIC_AUTH_TOKEN, адрес — в ANTHROPIC_BASE_URL.

Подробнее: Claude Code из России без VPN: как подключить · Подписка или API: сколько стоит Claude Code

Ошибки при работе через шлюз

Если Claude Code подключён через claude-gateway.ru, часть ошибок формирует сам шлюз до обращения к Anthropic. Ниже — полный список таких ответов с реальными кодами и текстами. Все остальные ошибки — 400, 404, 413, 500, 529 и прочие — шлюз передаёт от Anthropic как есть, с тем же кодом и телом, поэтому для них действует всё, что написано выше.

• 402 может прийти и при ненулевом остатке, если его не хватает на резерв под конкретный запрос: длинный ответ дорогой модели требует большего запаса.
• 429 от шлюза касается только одновременных запросов, а не их числа в минуту: несколько сессий Claude Code с субагентами легко упираются в этот порог.
• Проверить, что токен рабочий, можно бесплатным запросом GET /api/v1/models.

Подробнее: Документация шлюза: маршруты и модели