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

Как обрабатывать ошибки, возвращаемые сервером foura-mcp.

Каждый ответ с ошибкой от любого из четырех инструментов (foura_auto, foura_single, foura_proxy, foura_browser) является структурированным. LLM-агенты могут считывать поле code для логики повторных попыток без парсинга обычного текста.

Структура конверта

Каждая ошибка (isError: true) содержит блок structuredContent. Минимальный набор полей для каждой ошибки:

{
  "service": "auto | single | proxy | browser",
  "code": "rate_limited",
  "error": "Rate limit exceeded"
}

При ошибках upstream с HTTP-статусом также присутствует status. Когда общий лимит платформы отклоняет вызов, envelope добавляет retryAfter, current.{concurrency, rpm} и limits.{maxConcurrency, maxRpm} в том же формате, что и базовые ошибки REST API.

Когда вызов отклоняется из-за лимита вашего тарифного плана, код указывает именно на этот лимит: plan_limit_, за которым следует credits, bandwidth, rate, concurrency, browser_daily, premium или feature. retryAfter содержит время ожидания, если ожидание сбрасывает ограничение, и отсутствует для лимитов, которые ожиданием не сбросить, например для функции, не входящей в тарифный план. plan_limit_browser_daily также не содержит retryAfter: сброс происходит в полночь по UTC. plan_limit_credits и plan_limit_bandwidth ограничивают retryAfter 24 часами и добавляют resets_at, точный момент окончания расчетного периода, поэтому проверьте resets_at перед планированием повторного запроса.

В foura_auto исчерпание лимита тарифного плана внутри цепочки возвращается как rate_limited или forbidden, а код плана содержится в reason.

Стабильные значения code

Код HTTP Значение Повтор безопасен?
ssrf_blocked н/д Целевой адрес является частным или зарезервированным (RFC 5735, RFC 6598, зарезервированные IPv6), URL не использует http(s), либо его имя хоста не удалось разрешить Нет, проверьте URL. Кратковременно завершившийся сбоем запрос разрешения можно повторить
upstream_non_json различается Upstream вернул тело, которое не является валидным JSON Возможно, требуется анализ
output_validation_failed н/д outputSchema на MCP-сервере отклонил ответ upstream, либо инструмент не смог завершить вызов (API key не настроен, API недоступен) Возможно: проверьте настройки, затем отправьте отчет
bad_request 400 Формат входных данных отклонен FourA API, целевой URL указывает на собственный API FourA вместо страницы (через него можно запрашивать только /inspect), URL содержит некодированный пробел (закодируйте его как %20), либо proxy указывает exit, который данный вызов не может использовать: premium exit при исчерпанном premium-трафике возвращает Managed exit: this proxy id cannot be pinned to a request. Запрос не выполняется, списания не происходят Нет, исправьте аргументы
auth_failed 401 FourA API key отсутствует, недействителен или деактивирован; это не относится к учетным данным целевого сайта Нет, исправьте ключ FourA
forbidden 403 Целевой ресурс вернул 403, и ваш validate отклонил его (проверка сайта, ограничение по стране) Нет, или переключитесь на foura_proxy
not_found 404 Целевой URL или endpoint не существует Нет
rate_limited 429 Общий поминутный лимит платформы, либо ответ 429 от целевого ресурса, который ваш validate отклонил. На foura_auto это также могут быть кредиты вашего плана, трафик или rate limit (см. reason) Да, подождите retryAfter, если он присутствует, иначе примените backoff
at_capacity 503 Достигнут лимит параллелизма (current.concurrency > limits.maxConcurrency), либо сервис отключен на обслуживание (error содержит Service disabled, retryAfter равен 60) Да, подождите retryAfter секунд
service_disabled 503 Зарезервировано. Сервис, отключенный на обслуживание, сейчас возвращает at_capacity, а инструмент, не включенный в ваш план, возвращает plan_limit_feature Обратитесь в поддержку
service_unavailable 503 Общая ошибка 503 от upstream Да, короткий backoff
upstream_error 500+ или 0 Целевой ресурс вернул ошибку сервера, либо на foura_proxy, foura_browser и foura_auto ответ так и не был получен Да, экспоненциальный backoff
upstream_client_error 4xx Другие ошибки 4xx, не указанные выше Обычно нет
upstream_unknown другое Запрос выполнен, но не дал принятого ответа: на foura_single целевой ресурс так и не ответил (таймаут, сброс соединения), а на любом инструменте ваш validate отклонил ответ 2xx или 3xx. См. status и error Требуется анализ
no_eligible_proxy н/д Ни один proxy не соответствует строгому списку разрешений exitCountries; details.exitCountries содержит нормализованный scope Повторите позже; меняйте scope только явно
plan_limit_credits 429 Ежемесячные кредиты вашего плана исчерпаны Да, после retryAfter, или измените план
plan_limit_bandwidth 429 Лимит трафика вашего плана исчерпан для текущего расчетного периода Да, после retryAfter, или измените план
plan_limit_rate 429 Лимит запросов в минуту вашего плана для этого endpoint Да, после retryAfter
plan_limit_concurrency 429 Лимит одновременных запросов вашего плана для этого endpoint Да, после retryAfter
plan_limit_browser_daily 429 Дневной лимит Browser вашего плана исчерпан Да, завтра, или используйте foura_single / foura_proxy
plan_limit_premium 403 Вы отправили exitClass: "premium" на плане, который не включает premium exits Нет, удалите параметр или измените план
plan_limit_feature 403 План не включает данный endpoint или эту возможность Нет, измените план

Ошибки уровня HTTP от MCP-сервера

Некоторые сбои происходят на транспортном уровне MCP, еще до вызова какого-либо инструмента. В таких случаях возвращаются необработанные ошибки JSON-RPC (без structuredContent):

HTTP Когда Что вы получаете
400 Неподдерживаемый заголовок MCP-Protocol-Version Unsupported MCP-Protocol-Version: <value>. Supported (from @modelcontextprotocol/sdk): 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07. Upgrade foura-mcp's SDK pin to extend.
401 Вызов инструмента или чтение ресурса без API-ключа. Получение списка инструментов и промптов работает без него Ошибка JSON-RPC + WWW-Authenticate: Bearer realm="foura-mcp"
403 Запрещенный заголовок Origin или Host (защита от DNS-rebinding, CVE-2025-66414) Origin <value> is not in the allowlist или Host <value> is not in the allowlist
405 GET или DELETE на /mcp (stateless-режим) Method not allowed in stateless mode. Use POST /mcp.
413 Тело запроса > 256 KB Стандартный 413 от Express

Списки разрешений для 403 настраиваются через переменные окружения FOURA_MCP_ALLOWED_HOSTS и FOURA_MCP_ALLOWED_ORIGINS при самостоятельном хостинге.

Отклоненные профили браузера

Профиль браузера, отсутствующий в каталоге, или профиль, переданный со значением unblocker равным false, возвращается как сбой upstream с указанием причины в error, и запрос не покидает FourA. Если комбинация browser, os и version не существует, в сообщении перечисляются доступные варианты, поэтому повторите запрос с одной из указанных комбинаций вместо прежней. Неизвестный идентификатор profile возвращает unknown profile без списка: найдите идентификатор в GET /api/profiles.

Это именно отказы, а не сбои в работе сервиса: повтор идентичного запроса завершится ошибкой, и никакой другой браузер взамен использован не был.

Стратегия повторных попыток

Пять категорий:

  • Запрос отклонен вашим тарифным планом, а не целевым ресурсом: любой код plan_limit_*. plan_limit_credits и plan_limit_bandwidth учитывают весь аккаунт, поэтому та же операция через другой инструмент также будет отклонена. plan_limit_rate, plan_limit_concurrency, plan_limit_browser_daily и plan_limit_feature относятся к одному endpoint, поэтому другой инструмент может сработать, если он подходит для этой задачи. Дождитесь окончания retryAfter, если он указан; в противном случае необходимо изменить тарифный план. plan_limit_premium можно устранить самостоятельно, снизив exitClass.
  • Подождать и повторить попытку: rate_limited, at_capacity, service_unavailable, upstream_error. Учитывайте retryAfter, если он передан. Используйте экспоненциальную задержку с джиттером (exponential backoff with jitter), если он отсутствует. Не отвечайте на это одновременным повторным запуском всех вызовов инструментов из очереди: вместо этого уменьшите количество параллельно выполняемых запросов.
  • Сохранить область видимости и повторить попытку позже: no_eligible_proxy. Не удаляйте exitCountries и не подменяйте страну не предупредив. Изменяйте или расширяйте allowlist только тогда, когда пользователь явно изменил требование.
  • Не повторять попытку до исправления входных данных или учетных данных: bad_request, auth_failed, not_found, ssrf_blocked. Для auth_failed проверьте API key сервиса FourA, а не учетные данные целевого сайта.
  • Сменить инструмент, когда этого требует контент: forbidden на foura_single может оправдать ограниченную попытку с foura_proxy. Используйте foura_browser, когда нужный контент требует JavaScript. После успешного выбора proxy передайте возвращенный идентификатор proxy в foura_browser.proxy вместо запуска нового выбора.

Пример повторных попыток (TypeScript, на стороне MCP)

async function callWithRetry(call: () => Promise<any>, maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const r = await call();
    if (!r.isError) return r;

    const code = r.structuredContent?.code;
    const wait = r.structuredContent?.retryAfter ?? Math.min(2 ** attempt, 30);

    if (["rate_limited", "at_capacity", "service_unavailable", "upstream_error"].includes(code)) {
      await new Promise((res) => setTimeout(res, wait * 1000));
      continue;
    }
    // Non-retryable, surface to caller
    throw new Error(`${code}: ${r.structuredContent?.error}`);
  }
  throw new Error("max retries exceeded");
}
  • MCP Server, четыре инструмента и их схемы
  • MCP Recipes, готовые промпты для рабочих процессов, поставляемые с сервером
  • API Errors, тот же формат конверта на уровне базового REST API
  • Rate Limits, лимиты учетной записи и платформы, стоящие за rate_limited и at_capacity
Обновлено: 13 ноября 2026 г.