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_creditsiplan_limit_bandwidthzliczają 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_dailyiplan_limit_featuredotyczą jednego endpointu, więc inne narzędzie może nadal działać, jeśli jest w stanie wykonać to zadanie. OdczekajretryAfter, jeśli jest dostępny; w przeciwnym razie konieczna jest zmiana planu.plan_limit_premiummożesz rozwiązać samodzielnie, usuwającexitClass. - Odczekaj i ponów próbę:
rate_limited,at_capacity,service_unavailable,upstream_error. RespektujretryAfter, 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 usuwajexitCountriesani 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 przypadkuauth_failedzweryfikuj klucz API FourA, a nie poświadczenia witryny docelowej. - Przełącz narzędzie, gdy wymaga tego treść:
forbiddenwfoura_singlemoże uzasadniać ograniczoną próbę użyciafoura_proxy. Użyjfoura_browser, gdy wymagana treść potrzebuje JavaScriptu. Po pomyślnym wyborze proxy przekaż zwrócony identyfikatorproxydofoura_browser.proxyzamiast 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");
}
Powiązane
- Serwer MCP, cztery narzędzia i ich schematy
- Gotowe scenariusze MCP, prompty workflow dostarczane z serwerem
- Błędy API, ta sama powłoka na bazowej warstwie REST API
- Rate limity, limity konta i platformy stojące za
rate_limitediat_capacity