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) jest ustrukturyzowana. Agenci LLM mogą odczytywać pole code na potrzeby logiki ponawiania prób bez konieczności parsowania 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"
}

Przy błędach upstream ze statusem HTTP obecne jest również status. Gdy wspólny limit platformy odrzuca wywołanie, envelope dodaje retryAfter, current.{concurrency, rpm} oraz limits.{maxConcurrency, maxRpm}, w tej samej strukturze co bazowe błędy REST API.

Gdy wywołanie zostanie odrzucone przez jeden z limitów Twojego planu, kodem JEST ten limit: plan_limit_, po którym następuje credits, bandwidth, rate, concurrency, browser_daily, premium lub feature. retryAfter zawiera czas oczekiwania, jeśli odczekanie rozwiązuje problem, i jest nieobecne w przypadku limitu, którego oczekiwanie nie resetuje, takiego jak funkcja nieuwzględniona w planie. plan_limit_browser_daily również nie zawiera retryAfter: resetuje się o północy UTC. plan_limit_credits i plan_limit_bandwidth ograniczają retryAfter do 24 godzin i dodają resets_at, czyli dokładny koniec okresu rozliczeniowego, dlatego sprawdź resets_at przed zaplanowaniem ponowienia.

W foura_auto limit planu napotkany wewnątrz drabinki powraca jako rate_limited lub forbidden, z kodem planu w reason.

Stabilne wartości code

Kod HTTP Znaczenie Bezpieczne ponowienie?
ssrf_blocked nd. Cel to adres prywatny lub zastrzeżony (RFC 5735, RFC 6598, zastrzeżone IPv6), URL nie używa http(s) lub jego nazwa hosta nie została rozwiązana Nie, sprawdź URL. Krótkotrwały błąd rozpoznawania nazwy można ponowić
upstream_non_json różne Serwer nadrzędny zwrócił treść, która nie jest poprawnym formatem JSON Być może, zbadaj przyczynę
output_validation_failed nd. outputSchema serwera MCP odrzucił odpowiedź serwera nadrzędnego albo narzędzie nie mogło ukończyć wywołania (brak skonfigurowanego klucza API, API nieosiągalne) Być może: sprawdź konfigurację, a następnie zgłoś
bad_request 400 Format danych odrzucony przez FourA API, docelowy URL wskazuje na własne API FourA zamiast na stronę (tylko /inspect można tam pobierać), URL zawiera niezakodowaną spację (zakoduj ją jako %20) lub proxy wskazuje węzeł wyjściowy, którego wywołanie nie może użyć: węzeł premium po wyczerpaniu transferu premium zwraca Managed exit: this proxy id cannot be pinned to a request. Nic nie jest pobierane ani rozliczane Nie, popraw argumenty
auth_failed 401 Klucz FourA API jest nieobecny, nieprawidłowy lub dezaktywowany; nie dotyczy to danych uwierzytelniających strony docelowej Nie, popraw klucz FourA
forbidden 403 Cel odpowiedział 403, a Twój validate to odrzucił (weryfikacja witryny, blokada regionalna) Nie, lub przełącz na foura_proxy
not_found 404 Docelowy URL lub endpoint nie istnieje Nie
rate_limited 429 Współdzielony limit platformy na minutę lub kod 429 z celu, który Twój validate odrzucił. Na foura_auto mogą to być również kredyty planu, transfer lub limit zapytań (zobacz reason) Tak, odczekaj retryAfter gdy występuje, w przeciwnym razie zastosuj backoff
at_capacity 503 Osiągnięto limit współbieżności (current.concurrency > limits.maxConcurrency) lub usługa jest wyłączona z powodu prac konserwacyjnych (error wskazuje Service disabled, retryAfter to 60) Tak, odczekaj retryAfter s
service_disabled 503 Zastrzeżone. Usługa wyłączona na czas prac konserwacyjnych zwraca obecnie at_capacity, a narzędzie niedostępne w Twoim planie zwraca plan_limit_feature Skontaktuj się ze wsparciem
service_unavailable 503 Ogólny błąd 503 z serwera nadrzędnego Tak, krótki backoff
upstream_error 500+ lub 0 Cel odpowiedział błędem serwera, a w foura_proxy, foura_browser i foura_auto nigdy nie odpowiedziały Tak, wykładniczy backoff
upstream_client_error 4xx Inne kody 4xx nieuwzględnione powyżej Zazwyczaj nie
upstream_unknown inne Żądanie zostało wykonane, ale nie przyniosło zaakceptowanej odpowiedzi: w foura_single cel nigdy nie odpowiedział (timeout, odrzucone połączenie), a w dowolnym narzędziu Twój validate odrzucił odpowiedź 2xx lub 3xx. Sprawdź status i error Zbadaj przyczynę
no_eligible_proxy nd. Żadne proxy nie pasuje do restrykcyjnej białej listy exitCountries; details.exitCountries zawiera znormalizowany zakres Ponów próbę później; zmieniaj zakres wyłącznie jawnie
plan_limit_credits 429 Miesięczne kredyty w Twoim planie zostały wyczerpane Tak, po retryAfter lub zmień plan
plan_limit_bandwidth 429 Limit transferu w Twoim planie został wyczerpany w tym okresie rozliczeniowym Tak, po retryAfter lub zmień plan
plan_limit_rate 429 Liczba żądań na minutę w Twoim planie dla tego endpointu Tak, po retryAfter
plan_limit_concurrency 429 Liczba jednoczesnych żądań w Twoim planie dla tego endpointu Tak, po retryAfter
plan_limit_browser_daily 429 Dzienny limit Browser w Twoim planie został wyczerpany Tak, jutro lub użyj foura_single / foura_proxy
plan_limit_premium 403 Wysłano exitClass: "premium" w planie, który nie zawiera węzłów wyjściowych premium Nie, usuń parametr lub zmień plan
plan_limit_feature 403 Plan nie obsługuje tego endpointu ani tej funkcji Nie, zmień plan

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):

HTTP Kiedy Co widzisz
400 Nieobsługiwany nagłówek MCP-Protocol-Version 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 Wywołanie narzędzia lub odczyt zasobu bez klucza API. Listowanie narzędzi i promptów działa bez niego Błąd JSON-RPC + WWW-Authenticate: Bearer realm="foura-mcp"
403 Niedozwolony nagłówek Origin lub Host (ochrona przed DNS rebinding, CVE-2025-66414) Origin <value> is not in the allowlist lub Host <value> is not in the allowlist
405 GET lub DELETE na /mcp (tryb bezstanowy) Method not allowed in stateless mode. Use POST /mcp.
413 Rozmiar body żądania > 256 KB Domyślny 413 z Express

Listy dozwolonych dla błędu 403 można konfigurować za pomocą zmiennych środowiskowych przy self-hostingu przez FOURA_MCP_ALLOWED_HOSTS i FOURA_MCP_ALLOWED_ORIGINS.

Odrzucone profile przeglądarek

Profil przeglądarki, którego katalog nie może udostępnić, lub profil przesłany z unblocker ustawionym na false, zwraca błąd upstream z powodem w error, a żądanie nigdy nie opuszcza FourA. Dla nieistniejącej kombinacji browser, os i version komunikat wskazuje dostępne opcje, więc ponów próbę z jedną z wymienionych kombinacji zamiast tej samej. Nieznany identyfikator profile zwraca unknown profile bez listy: sprawdź identyfikator na GET /api/profiles.

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

Strategia ponawiania

Pięć kategorii:

  • Twój własny plan odrzucił żądanie, a nie cel: dowolny kod plan_limit_*. plan_limit_credits i plan_limit_bandwidth zliczają całe konto, więc ta sama operacja przez inne narzędzie również zostanie odrzucona. plan_limit_rate, plan_limit_concurrency, plan_limit_browser_daily i plan_limit_feature dotyczą jednego endpointu, więc inne narzędzie może nadal działać, jeśli jest w stanie wykonać to zadanie. Odczekaj retryAfter, jeśli jest dostępny; w przeciwnym razie konieczna jest zmiana planu. plan_limit_premium możesz rozwiązać samodzielnie, usuwając exitClass.
  • Odczekaj i ponów próbę: rate_limited, at_capacity, service_unavailable, upstream_error. Respektuj retryAfter, gdy jest obecny. Zastosuj wykładnicze wycofywanie z losowym rozrzutem (jitter), gdy go brakuje. Nie reaguj na to ponownym wysyłaniem wszystkich zakolejkowanych wywołań narzędzi naraz: zamiast tego zmniejsz liczbę zadań uruchamianych równolegle.
  • Zachowaj zakres i ponów próbę później: no_eligible_proxy. Nie usuwaj exitCountries ani nie podstawiaj po cichu innego kraju. Zmień lub rozszerz białą listę tylko wtedy, gdy użytkownik wyraźnie zmieni wymagania.
  • Nie ponawiaj prób do czasu poprawienia danych wejściowych lub poświadczeń: bad_request, auth_failed, not_found, ssrf_blocked. W przypadku auth_failed zweryfikuj klucz API FourA, a nie poświadczenia witryny docelowej.
  • Przełącz narzędzie, gdy wymaga tego treść: forbidden w foura_single może uzasadniać ograniczoną próbę użycia foura_proxy. Użyj foura_browser, gdy wymagana treść potrzebuje JavaScriptu. Po pomyślnym wyborze proxy przekaż zwrócony identyfikator proxy do foura_browser.proxy zamiast rozpoczynać nowy wybór.

Przykład ponawiania prób (TypeScript, po stronie 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");
}
Aktualizacja: 13 listopada 2026