Ошибки MCP Server

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

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

Структура envelope

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

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

При ошибках upstream с HTTP-статусом также присутствует status. Если вызов отклоняется общей квотой платформы, конверт содержит 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.

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

Фиксированные значения code

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

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

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

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

Профиль браузера, который каталог не может предоставить, или профиль, переданный со значением false в unblocker, возвращается как сбой upstream с указанием причины в error, при этом запрос не покидает FourA. В сообщении перечислено, что доступно, поэтому повторите попытку с одной из указанных комбинаций вместо той же самой.

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

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

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

• Отказ со стороны вашего тарифного плана, а не целевого ресурса: любой код plan_limit_*. Та же операция через другой инструмент также будет отклонена, поэтому смена endpoint лишь тратит время. Дождитесь окончания retryAfter, если он есть; в противном случае необходимо изменить тарифный план. plan_limit_premium можно устранить самостоятельно, убрав exitClass.
• Подождать и повторить попытку: rate_limited, at_capacity, service_unavailable, upstream_error. Учитывайте retryAfter при наличии. Используйте экспоненциальную задержку с джиттером (exponential backoff with jitter), если заголовок отсутствует. Не пытайтесь решить проблему одновременным повтором всех вызовов инструментов из очереди: вместо этого уменьшите количество параллельных запросов.
• Сохранить область видимости и повторить позже: no_eligible_proxy. Не удаляйте exitCountries и не подменяйте страну скрытно. Изменяйте или расширяйте список разрешенных только тогда, когда пользователь явно меняет требования.
• Не повторять попытку до исправления входных данных или учетных данных: bad_request, auth_failed, not_found, ssrf_blocked. Для auth_failed проверьте ключ API FourA, а не учетные данные целевого сайта.
• Переключить инструмент, если этого требует контент: forbidden на foura_single может обосновать ограниченную попытку с foura_proxy. Используйте foura_browser, когда для получения нужного контента требуется JavaScript. После успешного выбора прокси передайте возвращенный ID 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