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

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

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

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

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

Код	Тип	Описание	Серьёзность
400	Ошибка клиента	Неверный формат запроса	Низкая
401	Ошибка аутентификации	Недействительный API Key	Средняя
403	Ошибка доступа	Доступ запрещён	Средняя
429	Ошибка ограничения частоты	Слишком частые запросы	Средняя
500	Ошибка сервера	Внутренняя ошибка	Высокая
502	Ошибка шлюза	Вышестоящий сервис недоступен	Высокая
503	Сервис недоступен	Временная перегрузка сервиса	Высокая
529	Перегрузка API	Перегрузка Claude API	Высокая

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

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

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

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

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

Слишком частые запросы: быстрая последовательная отправка множества запросов
Слишком много параллельных запросов: одновременный запуск нескольких экземпляров Claude Code
Достигнут лимит потребления токенов: за короткое время израсходовано большое количество токенов
Исчерпана квота аккаунта: дневная/месячная квота полностью использована

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

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

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

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

Снизьте частоту запросов, избегайте быстрой последовательной отправки
Используйте команду /compact для сжатия контекста
Разделите крупные задачи на небольшие и выполняйте их по очереди
Рассмотрите переход на тариф с более высокой квотой

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

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

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

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

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

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

Временная недоступность вышестоящего сервиса: проблемы с серверами Anthropic API
Разрыв сетевого соединения: обрыв связи в процессе запроса
Проблемы прокси-сервера: сбой промежуточного узла
Тайм-аут запроса: время ответа превысило допустимый предел шлюза

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

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

# Проверьте сетевое подключение
curl -I https://asia.qcode.cc/api

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

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

Проверьте стабильность локальной сети
Попробуйте сменить сетевое окружение
Используйте VPN или более стабильную сеть
При систематическом возникновении обратитесь в техническую поддержку

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

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

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

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

Error: 401 Unauthorized
Invalid API key or authentication token.

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

Ошибка в API Key: при копировании пропущены символы или добавлены лишние пробелы
API Key истёк: подписка истекла
API Key заблокирован: блокировка за нарушение правил использования
Переменная окружения не задана: ANTHROPIC_AUTH_TOKEN не настроен

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

Проверка API Key:

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

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

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

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

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

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

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

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

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

Неверная конечная точка API: использован неправильный адрес API
Недостаточные права: текущий тариф не поддерживает данную функцию
Региональные ограничения: некоторые функции недоступны в определённых регионах
Аномальное состояние аккаунта: аккаунт ограничен

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

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

Проверьте правильность настройки конечной точки API
Убедитесь, что тариф включает необходимую функцию
Обратитесь в службу поддержки для проверки настроек прав

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

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

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

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

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

Неверный формат запроса: некорректный формат JSON
Отсутствие параметров: обязательные параметры не указаны
Недопустимые значения параметров: значения выходят за пределы допустимого диапазона
Проблемы кодировки: специальные символы не закодированы правильно

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

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

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

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

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

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

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

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

Ошибка на стороне сервера: проблема в коде API-сервера
Нехватка ресурсов: ресурсы сервера временно исчерпаны
Ошибка конфигурации: проблема с настройкой сервера

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

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

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

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

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.

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

Перегрузка сервера: объём запросов превышает возможности сервера
Плановое обслуживание: сервер проходит техническое обслуживание
Исчерпание ресурсов: ресурсы сервера временно недостаточны

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

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

Подождите несколько минут и повторите попытку
Используйте стратегию экспоненциальной задержки при повторных попытках
Проверьте объявления о статусе сервиса

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

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

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

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

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

Резкий рост глобального потребления: всплеск числа пользователей Claude по всему миру
Часы пик: концентрация запросов в рабочее время
Популярные события: определённые события вызывают резкий рост нагрузки

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

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

Подождите 2–5 минут и повторите попытку
Избегайте часов пик (рабочее время в США)
Используйте /compact для уменьшения потребления токенов

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

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

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

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

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

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

Нестабильная сеть: низкое качество сетевого соединения
Слишком большой объём запроса: слишком много токенов в контексте
Слишком сложная задача: длительное время обработки ИИ
Медленный ответ сервера: высокая нагрузка на сервер

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

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

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

Проверьте стабильность сетевого подключения
Используйте /compact для сжатия контекста
Разделите сложные задачи на простые
Попробуйте более стабильное сетевое окружение

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

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

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

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

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

Неверная команда сервера: ошибка в имени пакета npx или пакет не установлен
Отсутствие переменных окружения: не задан токен, необходимый MCP-серверу
Тайм-аут: слишком долгий запуск или выполнение сервера
Недостаточные права: нет прав доступа к файловой системе/базе данных

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

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

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

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

Используйте /mcp для проверки состояния подключения к серверу
Используйте /doctor для запуска автоматической диагностики
Проверьте формат конфигурации в ~/.claude/settings.json или .mcp.json
Убедитесь, что необходимые переменные окружения заданы ($GITHUB_TOKEN и т.д.)
Увеличьте тайм-аут: задайте переменные окружения MCP_TIMEOUT и MCP_TOOL_TIMEOUT

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

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

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

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

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

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

# Проверьте доступность конечной точки API
curl -I https://asia.qcode.cc/api

# Проверьте DNS-разрешение
nslookup asia.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 "скажи привет"

# Простой скрипт повторных попыток
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
}