Ошибки сервера 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. При ошибках rate limit и емкости конверт добавляет retryAfter, current.{concurrency, rpm} и limits.{maxConcurrency, maxRpm} в том же формате, что и базовые ошибки REST API.

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

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

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

Списки разрешений для 403 настраиваются через переменные среды для self-hoster-ов с помощью FOURA_MCP_ALLOWED_HOSTS и FOURA_MCP_ALLOWED_ORIGINS.

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

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

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

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

Четыре категории:

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