Грешки на MCP сървъра

Как да обработвате грешки, върнати от 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 errors.

Когато някой от лимитите на вашия план откаже извикване, кодът Е този лимит: 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 n/a Целта е частен или резервиран адрес (RFC 5735, RFC 6598, IPv6 reserved), URL адресът не е http(s), или името на хоста не се разреши Не, проверете URL адреса. Краткотрайно неуспешно търсене може да бъде повторено
upstream_non_json варира Upstream услугата върна тяло, което не е валиден JSON Възможно е, проучете
output_validation_failed n/a Сървърът MCP на outputSchema отхвърли upstream отговора, или инструментът не успя да завърши извикването изобщо (няма конфигуриран API ключ, API е недостъпен) Възможно е: проверете конфигурацията, след това докладвайте
bad_request 400 Форматът на входните данни е отхвърлен от FourA API, целевият URL сочи към собствения API на FourA вместо към страница (само /inspect може да се извлича там), URL съдържа неенкоднат интервал (енкоднете го като %20), или proxy указва изходна точка, която извикването не може да използва: премиум изход след изчерпване на премиум трафика връща Managed exit: this proxy id cannot be pinned to a request. Нищо не се извлича и не се таксува Не, коригирайте аргументите
auth_failed 401 FourA API ключът липсва, невалиден е или е деактивиран; това не се отнася за идентификационни данни на целевия сайт Не, коригирайте 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 n/a Няма proxy, съответстващо на строгия exitCountries списък с разрешени; details.exitCountries съдържа нормализирания обхват Опитайте отново по-късно; променяйте обхвата само изрично
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" при план, който не включва премиум изходни точки Не, премахнете параметъра или сменете плана
plan_limit_feature 403 Планът не включва този endpoint или тази функционалност Не, сменете плана

Грешки на HTTP ниво от MCP сървъра

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

HTTP Кога Какво виждате
400 Неподдържан MCP-Protocol-Version header 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 key. Извеждането на инструменти и prompts работи без такъв JSON-RPC грешка + WWW-Authenticate: Bearer realm="foura-mcp"
403 Забранен Origin или Host header (защита срещу 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 Request body > 256 KB Express по подразбиране 413

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

Отхвърлени браузърни профили

Браузърен профил, който каталогът не може да предостави, или профил, изпратен с unblocker със стойност false, се връща като upstream грешка с причината в error и заявката изобщо не напуска FourA. За несъществуваща комбинация от browser, os и version съобщението посочва наличните варианти, така че опитайте отново с някоя от изброените комбинации вместо със същата. Неизвестен profile id връща 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 с jitter, когато липсва. Не отговаряйте, като пускате отново всички извиквания на инструменти наведнъж: вместо това намалете броя на паралелно изпълняваните.
  • Запазете обхвата и опитайте отново по-късно: no_eligible_proxy. Не премахвайте exitCountries и не заменяйте мълчаливо с друга държава. Променяйте или разширявайте allowlist само когато потребителят изрично промени изискването.
  • Не опитвайте отново, докато входните данни или идентификационните данни не бъдат коригирани: bad_request, auth_failed, not_found, ssrf_blocked. За auth_failed проверете FourA API ключа, а не идентификационните данни за целевия сайт.
  • Сменете инструмента, когато съдържанието го изисква: forbidden при foura_single може да оправдае ограничен foura_proxy опит. Използвайте foura_browser, когато желаното съдържание изисква JavaScript. След успешен избор на proxy, подайте върнатия proxy ID във foura_browser.proxy, вместо да стартирате нов избор.

Retry пример (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 г.