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

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

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

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

---

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

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

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

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

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

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

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

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

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

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

**Немедленные меры**:
```bash
# Подождите 30–60 секунд и повторите попытку
sleep 60 && claude "ваш вопрос"
```

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

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

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

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

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

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

---

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

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

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

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

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

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

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

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

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

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

**Немедленные меры**:
```bash
# Проверьте сетевое подключение
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 недействителен или не предоставлена корректная информация для аутентификации.

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

```text
Error: 401 Unauthorized
Invalid API key or authentication token.
```

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

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

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

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

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

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

**Проверка API Key**:
```bash
# Проверьте переменную окружения
echo $ANTHROPIC_AUTH_TOKEN

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

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

1. Войдите в [панель управления QCode.cc](https://qcode.cc/dashboard) и проверьте статус API Key

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

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

---

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

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

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

```text
Error: 402 Payment Required
```

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

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

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

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

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

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

### Что делать

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

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

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

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

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

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

Все четыре домена работают с одним ключом, поэтому переключение не требует других изменений в конфигурации. См. [Эндпоинты и форматы API](/docs/getting-started/endpoints-and-api-paths).

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

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

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

Укажите время, id модели и домен подключения и свяжитесь с нами через [онлайн-чат](javascript:void(Tawk_API.toggle())) или [hi@qcode.cc](mailto:hi@qcode.cc).


### `INSUFFICIENT_BALANCE` / `Insufficient account balance`

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

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

---

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

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

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

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

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

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

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

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

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

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

```bash
# Убедитесь, что конечная точка 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; общий порядок — в [руководстве по устранению неполадок](/docs/reference/troubleshooting).

---

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

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

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

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

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

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

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

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

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

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

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

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

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

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

---

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

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

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

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

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

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

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

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

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

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

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

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

2. Проверьте статус сервиса на [QCode.cc](https://qcode.cc)

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

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

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

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

**Способ устранения**: см. раздел «Предотвращение переполнения при длинных сессиях» в статье [Управление контекстом](/docs/usage/context-management).

---

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

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

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

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

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

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

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

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

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

```bash
# Повтор с экспоненциальной задержкой
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-сервиса.

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

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

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

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

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

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

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

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

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

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

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

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

---

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

---

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

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

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

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

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

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

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

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

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

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

```bash
# Используйте команду /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. Запустите автоматическую диагностику

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

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

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

```bash
# Проверьте доступность конечной точки 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. Проверьте переменные окружения

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

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

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

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

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

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

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

Посетите [QCode.cc](https://qcode.cc) для просмотра объявлений о статусе сервиса.

---

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

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

```bash
# Простой скрипт повторных попыток
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](https://qcode.cc/dashboard)

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

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

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

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

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

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

---

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

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

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

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

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

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

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

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

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

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