Перейти к основному содержимому

Ошибки подключения

Эта страница посвящена устранению различных сетевых проблем в Elftia. Она охватывает ошибки вызовов LLM API, сбои, связанные с proxy, проблемы SSL/TLS, ошибки подключения MCP и аномалии подключения Channel.

HTTP-коды состояния LLM API​

Когда вызов LLM API возвращает ошибку, HTTP-код состояния — самая важная подсказка для диагностики. Ниже приведены значения каждого кода состояния и способы устранения:

401 Unauthorized​

Значение: API Key недействителен или не указан.

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

  • API Key содержит лишние пробелы или переносы строк
  • API Key был отозван или истек
  • Формат API Key неверный (например, ключ OpenAI должен начинаться с sk-)
  • Используется ключ не того provider

Шаги решения:

  1. Перейдите в Settings → Provider Settings и повторно проверьте API Key.
  2. Скопируйте ключ полностью и замените существующее значение в поле ввода.
  3. Перейдите в консоль provider и убедитесь, что ключ все еще действителен.
  4. Если используется пул API Key, проверьте, нет ли в пуле недействительных ключей (отключенные ключи помечены серым).
к сведению

Когда API Key в пуле возвращает 401, этот ключ автоматически отключается, а система автоматически переключается на другой доступный ключ в пуле.

403 Forbidden​

Значение: Аутентификация прошла успешно, но прав недостаточно.

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

  • Недостаточный баланс аккаунта или не привязан способ оплаты
  • API Key не имеет доступа к запрошенной model
  • IP-адрес или регион ограничен provider
  • Ограничения прав на уровне organization/project

Шаги решения:

  1. Войдите в консоль provider и проверьте баланс аккаунта и статус оплаты.
  2. Убедитесь, что API Key имеет доступ к выбранной вами model (для некоторых продвинутых models требуются специальные разрешения).
  3. Если используется proxy, попробуйте переключиться на proxy-узел в другом регионе.
  4. Проверьте настройки organization и project в консоли provider.

429 Too Many Requests​

Значение: Частота запросов слишком высокая, сработало ограничение скорости.

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

  • За короткое время отправлено слишком много запросов
  • У аккаунта низкая квота запросов (бесплатный аккаунт или низкий тариф)
  • Несколько приложений используют один и тот же API Key

Шаги решения:

  1. Подождите некоторое время перед повторной попыткой. Elftia покажет уведомление о периоде ожидания.
  2. Если ошибка возникает часто, рассмотрите возможность повышения тарифа аккаунта provider.
  3. Настройте пул API Key, используя несколько ключей для распределения запросов.

Автоматическая обработка в Elftia:

  • При встрече с 429 текущий ключ входит в период ожидания (начиная с 60 секунд, экспоненциальная задержка до 15 минут).
  • Если настроен пул API Key, система автоматически переключается на другой доступный ключ и повторяет попытку.
  • Ключ автоматически восстанавливается после завершения периода ожидания.

500 Internal Server Error​

Значение: Внутренняя ошибка сервера provider.

Шаги решения:

  1. Это проблема на стороне provider, обычно она устраняется сама. Подождите несколько минут и повторите попытку.
  2. Проверьте страницу статуса provider на наличие известных инцидентов.
  3. Если проблема сохраняется, попробуйте переключиться на другую model или provider.

502 Bad Gateway​

Значение: Ошибка gateway/load balancer у provider.

Шаги решения:

  1. Обычно это временная проблема; подождите 1–5 минут и повторите попытку.
  2. Проверьте страницу статуса provider.
  3. Если используется пользовательский Base URL (сторонний relay), проверьте, работает ли relay-сервис.

503 Service Unavailable​

Значение: Сервис provider временно недоступен (техническое обслуживание или перегрузка).

Шаги решения:

  1. Дождитесь восстановления сервиса provider.
  2. Переключитесь на резервный provider, чтобы продолжить работу.
  3. Проверьте страницу статуса provider и социальные сети, чтобы узнать время восстановления.

529 Overloaded​

Значение: Сервер provider перегружен (код состояния, специфичный для Anthropic).

Шаги решения:

  1. Подождите некоторое время и повторите попытку.
  2. Если настроен пул API Key, система автоматически переключит ключи и повторит попытку.
  3. Попробуйте использовать меньшую model (например, Claude Haiku вместо Claude Opus), чтобы снизить нагрузку на сервер.

Автоматическая обработка в Elftia: Как и 429, запускает механизм ожидания и автоматического переключения ключей.

Ошибки, связанные с proxy​

ECONNREFUSED​

Значение: В подключении отказано; обычно proxy-сервис не запущен.

Error: connect ECONNREFUSED 127.0.0.1:7890

Шаги решения:

  1. Убедитесь, что proxy-клиент (Clash, V2Ray, Shadowsocks и т. д.) запущен.
  2. Проверьте, совпадает ли порт прослушивания proxy с портом, настроенным в Elftia.
  3. Убедитесь, что proxy слушает правильный адрес (127.0.0.1 или 0.0.0.0).
  4. Если proxy не нужен, переключитесь на "No Proxy" в Settings → General → Proxy.

ETIMEDOUT​

Значение: Тайм-аут подключения; proxy не может достичь целевого сервера.

Error: connect ETIMEDOUT api.openai.com:443

Шаги решения:

  1. Проверьте, работает ли upstream-подключение proxy (может ли proxy получить доступ к целевому домену).
  2. Проверьте, включают ли правила маршрутизации proxy домены LLM API.
  3. Попробуйте переключить proxy-узлы.
  4. Проверьте правила firewall.

ECONNRESET​

Значение: Подключение сброшено удаленной стороной; обычно proxy разрывает соединение в середине stream.

Шаги решения:

  1. Проверьте стабильность вашего proxy-подключения.
  2. Увеличьте настройки timeout у proxy.
  3. Если это длинный streaming-запрос (например, генерация большого объема кода), у proxy могут быть ограничения длительности соединения, которые нужно скорректировать.

Ошибки SSL/TLS​

UNABLE_TO_VERIFY_LEAF_SIGNATURE​

Значение: Не удается проверить сертификат сервера; обычно это самоподписанный сертификат.

Распространенные сценарии:

  • Корпоративный proxy использует самоподписанный CA-сертификат для HTTPS-инспекции
  • Самостоятельно развернутый relay-сервис LLM API использует самоподписанный сертификат

Шаги решения:

  1. Установите сертификат от proxy/relay-сервиса и доверяйте ему.
    • Windows: Дважды щелкните файл сертификата → Install Certificate → Local Machine → Trusted Root Certification Authorities.
    • macOS: Дважды щелкните файл сертификата → Add to Keychain → Always Trust.
    • Linux: Скопируйте в /usr/local/share/ca-certificates/ → Выполните sudo update-ca-certificates.
  2. Перезапустите Elftia, чтобы изменения сертификата вступили в силу.

CERT_HAS_EXPIRED​

Значение: SSL-сертификат сервера истек.

Шаги решения:

  1. Если это самостоятельно развернутый сервис, обновите SSL-сертификат.
  2. Если это публичный сервис, проблема обычно временная; повторите попытку позже.
  3. Проверьте правильность системного времени (неверное системное время может привести к тому, что действительные сертификаты будут помечены как истекшие).

ERR_TLS_CERT_ALTNAME_INVALID​

Значение: Домен в сертификате не совпадает с фактическим доменом доступа.

Шаги решения:

  1. Проверьте, правильно ли указан Base URL provider.
  2. Если используется пользовательский endpoint, убедитесь, что сертификат сервера покрывает используемый вами домен.

Ошибки подключения MCP​

stdio mode — ENOENT​

Значение: Не удается найти команду запуска MCP server.

Error: spawn npx ENOENT

Шаги решения:

  1. Убедитесь, что программа, указанная в поле command, установлена:
    • npx / node: требуется установить Node.js.
    • uvx / python: требуется установить Python и uv.
  2. Вручную выполните команду в terminal, чтобы проверить, исполняется ли она.
  3. Проверьте статус установки инструментов в Settings → General → Environment.
  4. Если инструмент установлен, но ошибка сохраняется, возможно, нужно перезапустить Elftia, чтобы обновить переменные окружения PATH.

stdio mode — Процесс завершается сразу после запуска​

Симптом: MCP server кратко показывает подключение, затем отключается.

Возможные причины:

  • Отсутствуют необходимые npm/pip зависимости
  • Неверные параметры запуска
  • Отсутствуют необходимые переменные окружения

Шаги решения:

  1. Вручную выполните команду MCP server в terminal, чтобы увидеть вывод ошибок: 
    npx -y @modelcontextprotocol/server-filesystem /path
  2. Проверьте отсутствующие пакеты зависимостей и установите их вручную: 
    npm install -g @modelcontextprotocol/server-filesystem
  3. Убедитесь, что env в конфигурации MCP содержит все необходимые переменные окружения.

SSE/HTTP mode — Тайм-аут подключения​

Симптом: Подключение к удаленному MCP server истекает по времени.

Шаги решения:

  1. Убедитесь, что MCP server запущен и доступен из вашей сети.
  2. Попробуйте открыть URL MCP server в browser, чтобы проверить доступность.
  3. Проверьте, разрешает ли firewall доступ к порту MCP server.
  4. Если используется proxy, убедитесь, что правила proxy разрешают доступ к адресу MCP server.

SSE mode — Подключение часто обрывается​

Симптом: После установления SSE-подключение часто обрывается и переподключается.

Возможные причины:

  • Нестабильная сеть
  • Слишком короткие настройки timeout подключения у proxy или load balancer
  • Сам MCP server нестабилен

Шаги решения:

  1. Проверьте стабильность сетевого подключения.
  2. Если используется proxy или reverse proxy, увеличьте настройки timeout подключения и idle timeout.
  3. Свяжитесь с сопровождающим MCP server, чтобы подтвердить статус сервиса.

Ошибки подключения Channel​

Сбой подключения Discord Bot​

Возможные причины:

  • Bot Token недействителен или истек
  • Bot не приглашен на целевой server
  • У Bot нет необходимых разрешений
  • Ограничение скорости Discord API

Шаги решения:

  1. Убедитесь, что Bot Token корректен в Discord Developer Portal.
  2. Убедитесь, что Bot приглашен на целевой Discord server с правом отправлять сообщения.
  3. Проверьте, включены ли Privileged Gateway Intents у Bot.

Сбой подключения Telegram Bot​

Возможные причины:

  • Bot Token недействителен
  • Сеть не может получить доступ к Telegram API (api.telegram.org)
  • Другой клиент использует тот же Bot Token

Шаги решения:

  1. Убедитесь, что Bot Token корректен через @BotFather.
  2. Убедитесь, что ваша сеть может получить доступ к api.telegram.org (может потребоваться proxy).
  3. Убедитесь, что ни одно другое приложение не использует тот же Bot Token.

Ограничение скорости и механизм backoff​

В Elftia встроена интеллектуальная обработка ограничений скорости:

Автопереключение пула API Key​

Когда один ключ сталкивается с ошибками 429/529:

  1. Текущий ключ входит в период ожидания.
  2. Система сразу пробует следующий доступный ключ в пуле.
  3. Если запрос успешен, пользователь почти ничего не замечает.
  4. Ожидание использует экспоненциальный backoff: 60s → 120s → 240s → ... → максимум 15 минут.
  5. Ключ автоматически восстанавливается после завершения периода ожидания.

Session Affinity​

Чтобы поддерживать эффективность prompt cache у LLM provider, одна и та же chat session старается использовать один и тот же API Key:

  • Первый запрос выбирает ключ с помощью weighted round-robin.
  • Последующие запросы отдают приоритет тому же ключу.
  • Переключение происходит только если привязанный ключ недоступен (охлаждается или отключен).

Обработка постоянных отказов​

Когда ключ возвращает 401/403, ключ считается постоянно недействительным:

  • Этот ключ автоматически отключается (помечается как недоступный).
  • Система переключается на другой ключ.
  • Вы увидите отключенный ключ в пуле API Key в настройках provider.

Firewall и антивирусное ПО​

Firewall блокирует исходящие подключения​

Симптом: Все вызовы LLM API завершаются timeout или отклоняются.

Шаги решения:

  1. Добавьте Elftia в allowlist вашего firewall.
    • Windows Defender Firewall: Control Panel → Windows Defender Firewall → Allow an app through firewall → Add Elftia.
    • macOS: System Preferences → Security & Privacy → Firewall → Allow Elftia.
  2. Если используется корпоративный firewall, обратитесь к IT-администратору, чтобы открыть исходящий доступ к:
    • api.openai.com (OpenAI)
    • api.anthropic.com (Anthropic)
    • generativelanguage.googleapis.com (Google Gemini)
    • api.deepseek.com (DeepSeek)

Ложные срабатывания антивируса​

Симптом: Антивирус блокирует запуск Elftia или сетевые подключения.

Шаги решения:

  1. Добавьте каталог установки Elftia в исключения/whitelist антивируса.
  2. Распространенные пути для исключения:
    • Windows: C:\Users\<username>\AppData\Local\Elftia\
    • macOS: /Applications/Elftia.app

Быстрая проверка сетевой доступности​

При проблемах с подключением выполняйте диагностику в таком порядке:

  1. Базовая сеть: откройте любую веб-страницу в browser, чтобы убедиться, что сеть работает.
  2. Разрешение DNS: выполните ping api.openai.com (или соответствующий домен provider), чтобы убедиться, что домен разрешается.
  3. Доступность порта: выполните curl -I https://api.openai.com, чтобы убедиться, что порт 443 доступен.
  4. Тест proxy: если используется proxy, задайте переменные окружения proxy в terminal и повторите команды выше.
  5. Тест Elftia: используйте "Test Connection" в настройках provider в Elftia.

Если шаги 1–4 успешны, но шаг 5 завершается ошибкой, возможно, проблема в конфигурации proxy в Elftia; см. Использование proxy, чтобы настроить заново.

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