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

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

Всеки response с грешка от който и да е от четирите инструмента (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"
}

При грешки от източника с HTTP статус присъства и status. При грешки за rate limit и капацитет обвивката добавя retryAfter, current.{concurrency, rpm} и limits.{maxConcurrency, maxRpm} със същата структура като основния REST API errors.

Стабилни стойности на code

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

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

Списъците с разрешения за 403 могат да се конфигурират чрез средата за самостоятелно хостващи потребители чрез FOURA_MCP_ALLOWED_HOSTS и FOURA_MCP_ALLOWED_ORIGINS.

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

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

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

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

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

• Изчакайте и опитайте отново: 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 проверете API ключа за FourA, а не идентификационните данни за целевия сайт.
• Сменете инструмента, когато съдържанието го изисква: forbidden при foura_single може да оправдае ограничен опит с foura_proxy. Използвайте foura_browser, когато желаното съдържание се нуждае от JavaScript. След успешен избор на proxy, подайте върнатия 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, workflow промптове, включени в сървъра
• API Errors, същата обвивка на базовия слой на REST API