Справочник кодов ошибок

Распространённые коды ошибок Claude Code и способы их устранения

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

Краткая таблица кодов ошибок¶

429 — Превышение лимита запросов (Too Many Requests)¶

Одна из самых распространённых ошибок, означающая, что за короткий период было отправлено слишком много запросов.

Проявление ошибки¶

Error: 429 Too Many Requests
Rate limit exceeded. Please slow down your requests.

Распространённые причины¶

1. Слишком частые запросы: быстрая последовательная отправка множества запросов

2. Слишком много параллельных запросов: одновременный запуск нескольких экземпляров Claude Code

3. Достигнут лимит потребления токенов: за короткое время израсходовано большое количество токенов

4. Исчерпана квота аккаунта: дневная/месячная квота полностью использована

Способы устранения¶

Немедленные меры:

# Подождите 30–60 секунд и повторите попытку
sleep 60 && claude "ваш вопрос"

Долгосрочные меры:

1. Снизьте частоту запросов, избегайте быстрой последовательной отправки

2. Используйте команду /compact для сжатия контекста

3. Разделите крупные задачи на небольшие и выполняйте их по очереди

4. Рассмотрите переход на тариф с более высокой квотой

Преимущество QCode.cc: профессиональная балансировка нагрузки, пул из множества аккаунтов для распределения запросов, что эффективно снижает частоту ошибки 429.

502 — Ошибка шлюза (Bad Gateway)¶

Означает, что шлюз или прокси-сервер получил недействительный ответ от вышестоящего сервера.

Проявление ошибки¶

Error: 502 Bad Gateway
The server received an invalid response from the upstream server.

Распространённые причины¶

1. Временная недоступность вышестоящего сервиса: проблемы с серверами Anthropic API

2. Разрыв сетевого соединения: обрыв связи в процессе запроса

3. Проблемы прокси-сервера: сбой промежуточного узла

4. Тайм-аут запроса: время ответа превысило допустимый предел шлюза

Способы устранения¶

Немедленные меры:

# Проверьте сетевое подключение
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" https://api.qcode.cc/api/v1/models

# Подождите и повторите попытку
sleep 30 && claude "ваш вопрос"

Долгосрочные меры:

1. Проверьте стабильность локальной сети

2. Попробуйте сменить сетевое окружение

3. Используйте VPN или более стабильную сеть

4. При систематическом возникновении обратитесь в техническую поддержку

Преимущество QCode.cc: мультирегиональное развёртывание, CDN-ускорение, автоматическое переключение при сбоях, доступность 99,9%.

401 — Ошибка аутентификации (Unauthorized)¶

API Key недействителен или не предоставлена корректная информация для аутентификации.

Проявление ошибки¶

Error: 401 Unauthorized
Invalid API key or authentication token.

Распространённые причины¶

1. Ошибка в API Key: при копировании пропущены символы или добавлены лишние пробелы

2. API Key истёк: подписка истекла

3. API Key заблокирован: блокировка за нарушение правил использования

4. Переменная окружения не задана: ANTHROPIC_AUTH_TOKEN не настроен

Способы устранения¶

Проверка API Key:

# Проверьте переменную окружения
echo $ANTHROPIC_AUTH_TOKEN

# Убедитесь в правильности формата (начинается с cr_)
# Правильный формат: cr_xxxxxxxxxxxxxxxxxxxx

Порядок действий:

1. Войдите в панель управления QCode.cc и проверьте статус API Key

2. Убедитесь, что подписка не истекла

3. В случае блокировки обратитесь в службу поддержки (QCode.cc предоставляет услугу моментальной замены)

402 — Требуется оплата (Payment Required)¶

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

Как это выглядит¶

Error: 402 Payment Required

В Claude Code это выглядит как запрос, который просто не даёт ответа; из скрипта или SDK вы получаете HTTP 402.

Частые причины¶

1. Вышестоящий канал временно недоступен: шлюз QCode сам никогда не порождает 402 — он передаёт статус, полученный от вышестоящего канала

2. Сосредоточено на одной модели: в один и тот же момент у одной модели доля 402 может быть высокой, а остальные работают полностью нормально

3. Зависит от домена подключения: разные домены идут разными вышестоящими маршрутами, и вероятность получить 402 может отличаться в разы

4. Не связано с вашим балансом: исчерпание баланса или квоты тарифа не даёт 402 — в этом случае сообщение будет «достигнут дневной лимит расходов», см. Часто задаваемые вопросы (FAQ)

Что делать¶

1. Сменить модель (самое действенное)

# Переключение внутри сессии
/model sonnet

# Или указать при запуске
claude --model claude-sonnet-5

2. Сменить домен подключения

# Материковый Китай
export ANTHROPIC_BASE_URL=https://asia.qcode.cc/api

# Глобально (Route 53 выбирает ближайший узел)
export ANTHROPIC_BASE_URL=https://api.qcode.cc/api

Все четыре домена работают с одним ключом, поэтому переключение не требует других изменений в конфигурации. См. Эндпоинты и форматы API.

3. Не пишите плотный цикл повторов

402 не исчезает от немедленной повторной отправки; частые повторы только усугубляют ситуацию. Используйте экспоненциальную задержку либо просто смените модель — см. «Рекомендации по обработке ошибок» на этой странице.

4. Если повторяется — напишите в поддержку

Укажите время, id модели и домен подключения и свяжитесь с нами через онлайн-чат или hi@qcode.cc.

INSUFFICIENT_BALANCE / Insufficient account balance¶

В некоторых ответах 402/403 встречается JSON вида "code":"INSUFFICIENT_BALANCE", "message":"Insufficient account balance". Это не значит, что у вас закончился баланс QCode. Временное состояние одного из транзитных каналов, переданное дословно, — к вашему аккаунту оно не относится. Когда исчерпана ваша собственная квота, вы видите сообщение о дневном лимите расходов (см. FAQ).

Что делать: подождать и повторить / сменить модель / сменить домен доступа (шаги ①–③ выше подходят); если повторяется — в поддержку с request id. Общий порядок диагностики — в руководстве по устранению неполадок.

403 — Ошибка доступа (Forbidden)¶

Запрос отклонён сервером, обычно из-за недостаточных прав.

Проявление ошибки¶

Error: 403 Forbidden
You don't have permission to access this resource.

Распространённые причины¶

1. Неверная конечная точка API: использован неправильный адрес API

2. Недостаточные права: текущий тариф не поддерживает данную функцию

3. Региональные ограничения: некоторые функции недоступны в определённых регионах

4. Аномальное состояние аккаунта: аккаунт ограничен

Способы устранения¶

# Убедитесь, что конечная точка API настроена правильно
echo $ANTHROPIC_BASE_URL
# Должно быть: https://api.qcode.cc/api

1. Проверьте правильность настройки конечной точки API

2. Убедитесь, что тариф включает необходимую функцию

3. Обратитесь в службу поддержки для проверки настроек прав

INSUFFICIENT_BALANCE (если встречается на 403)¶

Если в теле 403 Forbidden есть INSUFFICIENT_BALANCE / Insufficient account balance, скорее всего это снова транзитное состояние одного из каналов, переданное дословно, — это не блокировка вашего аккаунта. Действуйте как в одноимённом подразделе раздела 402; общий порядок — в руководстве по устранению неполадок.

400 — Неверный запрос (Bad Request)¶

Неправильный формат запроса или недопустимые параметры.

Проявление ошибки¶

Error: 400 Bad Request
The request was malformed or contained invalid parameters.

Распространённые причины¶

1. Неверный формат запроса: некорректный формат JSON

2. Отсутствие параметров: обязательные параметры не указаны

3. Недопустимые значения параметров: значения выходят за пределы допустимого диапазона

4. Проблемы кодировки: специальные символы не закодированы правильно

Способы устранения¶

# Проверьте, не содержит ли ввод специальные символы
# Убедитесь в правильности формата запроса
claude -p "простой тест"

1. Упростите входные данные, исключите специальные символы

2. Убедитесь, что пути к файлам используют правильную кодировку

3. Проверьте формат параметров команды

500 — Внутренняя ошибка сервера (Internal Server Error)¶

Сервер столкнулся с непредвиденной ситуацией и не смог выполнить запрос.

Проявление ошибки¶

Error: 500 Internal Server Error
An unexpected error occurred on the server.

Распространённые причины¶

1. Ошибка на стороне сервера: проблема в коде API-сервера

2. Нехватка ресурсов: ресурсы сервера временно исчерпаны

3. Ошибка конфигурации: проблема с настройкой сервера

Способы устранения¶

# Подождите и повторите попытку
sleep 60 && claude "ваш вопрос"

# Используйте режим verbose для получения подробной информации
claude --verbose

1. Подождите несколько минут и повторите попытку

2. Проверьте статус сервиса на QCode.cc

3. При систематическом возникновении обратитесь в техническую поддержку, предоставив подробности ошибки

E015 — Переполнение контекста диалога¶

Возникает, когда контекст диалога приближается к пределу вместимости модели (~95%). QCode.cc оборачивает эту ошибку в ответ 429, чтобы инициировать повторную попытку:

429 {"error":{"code":"E015","message":"Internal server error"},"status":500}

Способ устранения: см. раздел «Предотвращение переполнения при длинных сессиях» в статье Управление контекстом.

503 — Сервис недоступен (Service Unavailable)¶

Сервер временно не может обработать запрос, обычно из-за перегрузки или технического обслуживания.

Проявление ошибки¶

Error: 503 Service Unavailable
The service is temporarily unavailable. Please try again later.

Распространённые причины¶

1. Перегрузка сервера: объём запросов превышает возможности сервера

2. Плановое обслуживание: сервер проходит техническое обслуживание

3. Исчерпание ресурсов: ресурсы сервера временно недостаточны

Способы устранения¶

# Повтор с экспоненциальной задержкой
for i in 1 2 4 8 16; do
  claude "ваш вопрос" && break
  echo "Повторная попытка, ожидание ${i} сек..."
  sleep $i
done

1. Подождите несколько минут и повторите попытку

2. Используйте стратегию экспоненциальной задержки при повторных попытках

3. Проверьте объявления о статусе сервиса

529 — Перегрузка API (Overloaded)¶

Код ошибки, специфичный для Claude API, означающий перегрузку API-сервиса.

Проявление ошибки¶

Error: 529 Overloaded
The API is temporarily overloaded. Please try again later.

Распространённые причины¶

1. Резкий рост глобального потребления: всплеск числа пользователей Claude по всему миру

2. Часы пик: концентрация запросов в рабочее время

3. Популярные события: определённые события вызывают резкий рост нагрузки

Способы устранения¶

# Повторите попытку позже
sleep 120 && claude "ваш вопрос"

1. Подождите 2–5 минут и повторите попытку

2. Избегайте часов пик (рабочее время в США)

3. Используйте /compact для уменьшения потребления токенов

Преимущество QCode.cc: механизм ротации пула аккаунтов, эффективно распределяющий нагрузку при перегрузках.

Тайм-аут подключения (Connection Timeout)¶

Запрос не был завершён в установленное время.

Проявление ошибки¶

Error: Connection timed out
The request timed out while waiting for a response.

Распространённые причины¶

1. Нестабильная сеть: низкое качество сетевого соединения

2. Слишком большой объём запроса: слишком много токенов в контексте

3. Слишком сложная задача: длительное время обработки ИИ

4. Медленный ответ сервера: высокая нагрузка на сервер

Способы устранения¶

# Проверьте сетевое подключение
ping api.qcode.cc

# Используйте режим compact для уменьшения контекста
/compact

1. Проверьте стабильность сетевого подключения

2. Используйте /compact для сжатия контекста

3. Разделите сложные задачи на простые

4. Попробуйте более стабильное сетевое окружение

Ошибки MCP-сервера¶

Ошибки, которые могут возникнуть при настройке или работе MCP-сервера.

Проявление ошибки¶

MCP server "xxx" failed to start
MCP connection timed out
MCP tool execution failed

Распространённые причины¶

1. Неверная команда сервера: ошибка в имени пакета npx или пакет не установлен

2. Отсутствие переменных окружения: не задан токен, необходимый MCP-серверу

3. Тайм-аут: слишком долгий запуск или выполнение сервера

4. Недостаточные права: нет прав доступа к файловой системе/базе данных

Способы устранения¶

# Используйте команду /mcp для проверки статуса сервера
/mcp

# Используйте /doctor для диагностики проблем конфигурации
/doctor

# Проверьте вручную, запускается ли MCP-сервер
npx -y @modelcontextprotocol/server-filesystem /tmp

1. Используйте /mcp для проверки состояния подключения к серверу

2. Используйте /doctor для запуска автоматической диагностики

3. Проверьте формат конфигурации в ~/.claude/settings.json или .mcp.json

4. Убедитесь, что необходимые переменные окружения заданы ($GITHUB_TOKEN и т.д.)

5. Увеличьте тайм-аут: задайте переменные окружения MCP_TIMEOUT и MCP_TOOL_TIMEOUT

Общий порядок диагностики¶

При возникновении любой ошибки выполните следующие шаги:

0. Запустите автоматическую диагностику¶

# Встроенный инструмент диагностики Claude Code
/doctor

Он автоматически проверит переменные окружения, подключение к API, состояние MCP-серверов и другие типичные проблемы конфигурации.

1. Проверьте сетевое подключение¶

# Проверьте доступность конечной точки API
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" https://api.qcode.cc/api/v1/models

# Проверьте DNS-разрешение
nslookup api.qcode.cc

2. Проверьте переменные окружения¶

# Проверьте все связанные переменные окружения
echo "BASE_URL: $ANTHROPIC_BASE_URL"
echo "AUTH_TOKEN: ${ANTHROPIC_AUTH_TOKEN:0:10}..."

3. Включите подробное логирование¶

# Используйте режим verbose для просмотра подробной информации
claude --verbose

# Или включите режим отладки
DEBUG=true claude

4. Выполните простой тестовый запрос¶

# Отправьте простой тестовый запрос
claude -p "скажи привет"

5. Проверьте статус сервиса¶

Посетите QCode.cc для просмотра объявлений о статусе сервиса.

Лучшие практики обработки ошибок¶

Реализация механизма повторных попыток¶

# Простой скрипт повторных попыток
retry_claude() {
  local max_attempts=3
  local attempt=1

  while [ $attempt -le $max_attempts ]; do
    claude "$@" && return 0
    echo "Попытка $attempt не удалась, повтор..."
    sleep $((attempt * 2))
    ((attempt++))
  done

  echo "Все попытки завершились неудачей"
  return 1
}

Мониторинг потребления¶

Регулярно проверяйте потребление API, чтобы не превысить квоту:

1. Войдите в панель управления QCode.cc

2. Просмотрите статистику потребления

3. Настройте уведомления о потреблении

Оптимизация запросов¶

1. Уменьшайте контекст: регулярно используйте /compact или /clear

2. Пакетная обработка: разделяйте крупные задачи на мелкие

3. Избегайте повторов: кэшируйте часто используемые результаты

Получение помощи¶

Если приведённые выше решения не помогли, обратитесь в техническую поддержку QCode.cc:

• Онлайн-чат: окно чата в правом нижнем углу сайта

• Время ответа: 1–2 часа в рабочее время

• Часы поддержки: 7x14 (ежедневно с 9:00 до 23:00)

При обращении предоставьте:

1. Полное сообщение об ошибке

2. Выполненную команду

3. Время возникновения

4. Префикс API Key (не сообщайте полный ключ)