Błędy serwera MCP

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

Każda odpowiedź z błędem z dowolnego z czterech narzędzi (foura_auto, foura_single, foura_proxy, foura_browser) jest ustrukturyzowana. Agenci LLM mogą odczytać pole code w celu wdrożenia logiki ponownych prób bez konieczności parsowania zwykłego tekstu.

Struktura koperty

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

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

W przypadku błędów upstream ze statusem HTTP obecny jest również status. W przypadku błędów związanych z limitami żądań i przepustowością, koperta dodaje retryAfter, current.{concurrency, rpm} i limits.{maxConcurrency, maxRpm}, o takim samym formacie jak podstawowe błędy REST API errors.

Stabilne wartości code

Błędy na poziomie HTTP z serwera MCP

Niektóre błędy występują w 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 środowisko dla hostujących samodzielnie za pomocą FOURA_MCP_ALLOWED_HOSTS i FOURA_MCP_ALLOWED_ORIGINS.

Odrzucone profile przeglądarki

Profil przeglądarki, którego katalog nie może zaprezentować, lub profil wysłany z parametrem unblocker ustawionym na false, wraca jako błąd upstream z podaniem przyczyny w error, a żądanie nigdy nie opuszcza FourA. Komunikat wymienia, co jest dostępne, więc spróbuj ponownie z jedną z wymienionych kombinacji zamiast z tą samą.

Są to odmowy, nie awarie: ponowienie identycznego żądania nie może się powieść i żadna inna przeglądarka nie została użyta w jego miejsce.

Strategia ponawiania prób

Cztery kategorie:

• Poczekaj i spróbuj ponownie: rate_limited, at_capacity, service_unavailable, upstream_error. Respektuj retryAfter, jeśli jest obecny. Użyj exponential backoff z jitterem, gdy go brakuje.
• Zachowaj zakres i spróbuj ponownie później: no_eligible_proxy. Nie usuwaj exitCountries ani nie podmieniaj po cichu na inny kraj. Zmień lub rozszerz listę dozwolonych tylko wtedy, gdy użytkownik wyraźnie zmieni wymaganie.
• Nie ponawiaj próby, dopóki dane wejściowe lub poświadczenia nie zostaną naprawione: bad_request, auth_failed, not_found, ssrf_blocked. Dla auth_failed, zweryfikuj klucz API FourA, a nie poświadczenia witryny docelowej.
• Zmień narzędzie, gdy wymaga tego zawartość: forbidden na foura_single może uzasadniać ograniczoną próbę foura_proxy. Użyj foura_browser, gdy żądana zawartość wymaga JavaScript. Po udanym wyborze proxy, przekaż zwrócony identyfikator proxy do foura_browser.proxy zamiast rozpoczynać nowy wybór.

Przykład ponawiania prób (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 przepływów pracy dostarczane z serwerem
• API Errors, ta sama koperta w bazowej warstwie REST API