Грешки на MCP Server

Как да обработвате грешки, върнати от foura-mcp server.

Всеки отговор за грешка от всеки от четирите инструмента (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 също присъства. Когато споделеният лимит на платформата откаже извикване, обвивката добавя 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):

Списъците с разрешени адреси (allowlists) за 403 могат да се конфигурират чрез променливи на средата при self-hosting през FOURA_MCP_ALLOWED_HOSTS и FOURA_MCP_ALLOWED_ORIGINS.

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

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

Това са откази, а не сривове в системата: повторният опит с идентична заявка не може да успее, като друг браузър не е бил използван на нейно място.

Стратегия за повторни опити (retry)

Пет категории:

• Вашият собствен план го отказа, а не целевият сайт: всеки plan_limit_* код. Същата задача през друг инструмент също ще бъде отказана, така че смяната на endpoint-и само губи време. Изчакайте retryAfter, когато има такъв; в противен случай планът трябва да се промени. plan_limit_premium е грешката, която можете да изчистите сами, като премахнете exitClass.
• Изчакайте и опитайте отново: rate_limited, at_capacity, service_unavailable, upstream_error. Спазвайте retryAfter, когато е наличен. Използвайте експоненциално отлагане (exponential backoff) с вариация (jitter), когато липсва. Не реагирайте, като изпратите наново всички извиквания на инструменти наведнъж: вместо това намалете броя на паралелно изпълняваните.
• Запазете обхвата и опитайте отново по-късно: no_eligible_proxy. Не премахвайте exitCountries и не заменяйте държавата тихо с друга. Променяйте или разширявайте списъка с разрешени стойности само когато потребителят изрично промени изискването.
• Не опитвайте отново, докато входните данни или идентификационните данни не бъдат коригирани: bad_request, auth_failed, not_found, ssrf_blocked. За auth_failed проверете FourA API key, а не идентификационните данни за целевия сайт.
• Сменете инструмента, когато съдържанието го изисква: 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, prompts за работни процеси, включени в сървъра
• API Errors, същият envelope в базовия REST API слой
• Rate Limits, лимитите за акаунта и платформата зад rate_limited и at_capacity