Błędy serwera MCP

Jak obsługiwać błędy zwracane przez serwer foura-mcp.

Każda odpowiedź błędu z dowolnego z czterech narzędzi (foura_auto, foura_single, foura_proxy, foura_browser) ma ustrukturyzowaną postać. Agenci LLM mogą odczytywać pole code na potrzeby logiki ponawiania prób bez konieczności parsowania tekstu.

Kształt koperty

Każdy błąd (isError: true) zawiera blok structuredContent. Minimalne pola każdego błędu:

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

W przypadku błędów upstream ze statusem HTTP obecne jest również status. Gdy współdzielony limit platformy odrzuca wywołanie, koperta dodaje retryAfter, current.{concurrency, rpm} oraz limits.{maxConcurrency, maxRpm}, o takiej samej strukturze jak bazowe błędy REST API.

Gdy wywołanie zostanie odrzucone przez jeden z limitów Twojego planu, kodem JEST ten limit: plan_limit_, a po nim credits, bandwidth, rate, concurrency, browser_daily, premium lub feature. retryAfter zawiera czas oczekiwania, jeśli odczekanie rozwiązuje problem, i nie występuje w przypadku limitu, którego oczekiwanie nie może zresetować, takiego jak funkcja niedostępna w danym planie. plan_limit_browser_daily również nie zawiera retryAfter: resetuje się o północy UTC.

W foura_auto limit planu osiągnięty w ramach drabinki zwracany jest jako rate_limited lub forbidden, z kodem planu w reason.

Stabilne wartości code

Błędy na poziomie HTTP z serwera MCP

Niektóre błędy występują na warstwie transportowej MCP, zanim jakiekolwiek narzędzie zostanie wywołane. Zwracają one surowe błędy JSON-RPC (brak structuredContent):

Listy dozwolonych dla 403 są konfigurowalne przez zmienne środowiskowe dla instalacji self-hosted za pomocą FOURA_MCP_ALLOWED_HOSTS oraz FOURA_MCP_ALLOWED_ORIGINS.

Odrzucone profile przeglądarek

Profil przeglądarki, którego katalog nie może udostępnić, lub profil wysłany z unblocker ustawionym na false, wraca jako błąd upstreamu z przyczyną w error, a żądanie nigdy nie opuszcza FourA. Komunikat wskazuje dostępne opcje, więc ponów próbę z jedną z wymienionych kombinacji zamiast tej samej.

Są to odrzucenia, a nie awarie: ponowienie identycznego żądania nie może się udać, a żadna inna przeglądarka nie została użyta w zamian.

Strategia ponawiania (retry)

Pięć kategorii:

• Twój własny plan odrzucił żądanie, nie cel: dowolny kod plan_limit_*. To samo zadanie wykonane przez inne narzędzie również zostanie odrzucone, więc zmiana endpointu marnuje tylko czas. Odczekaj retryAfter, jeśli jest podany; w przeciwnym razie plan musi ulec zmianie. plan_limit_premium możesz rozwiązać samodzielnie, usuwając exitClass.
• Odczekaj i ponów: rate_limited, at_capacity, service_unavailable, upstream_error. Przestrzegaj retryAfter, gdy jest obecny. Stosuj wykładnicze wycofywanie (exponential backoff) z szumem (jitter), gdy go brakuje. Nie reaguj ponownym wysyłaniem wszystkich zakolejkowanych wywołań narzędzi naraz: zamiast tego zmniejsz liczbę zadań wykonywanych równolegle.
• Zachowaj zakres i spróbuj ponownie później: no_eligible_proxy. Nie usuwaj exitCountries ani nie zastępuj po cichu innym krajem. Zmień lub rozszerz listę dozwolonych tylko wtedy, gdy użytkownik wyraźnie zmieni wymaganie.
• Nie ponawiaj, dopóki dane wejściowe lub poświadczenia nie zostaną poprawione: bad_request, auth_failed, not_found, ssrf_blocked. W przypadku auth_failed zweryfikuj klucz API FourA, a nie dane uwierzytelniające witryny docelowej.
• Zmień narzędzie, gdy wymaga tego zawartość: forbidden w foura_single może uzasadniać ograniczoną próbę foura_proxy. Użyj foura_browser, gdy żądana zawartość wymaga JavaScriptu. Po pomyślnym wyborze proxy przekaż zwrócony identyfikator proxy do foura_browser.proxy zamiast rozpoczynać nowy wybór.

Przykład ponawiania (TypeScript, strona 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");
}

Powiązane

• MCP Server, cztery narzędzia i ich schematy
• MCP Recipes, prompty workflow dostarczane z serwerem
• API Errors, ta sama koperta na poziomie bazowego REST API
• Rate Limits, limity konta i platformy stojące za rate_limited oraz at_capacity