# Błędy serwera MCP

> URL: https://foura.ai/pl/docs/mcp/errors
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

Jak obsługiwać błędy zwracane przez serwer [foura-mcp](https://foura.ai/docs/mcp/server).

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:

```json
{
  "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](https://foura.ai/docs/api/errors).

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`](https://foura.ai/docs/api/endpoints#browser-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)

```typescript
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](https://foura.ai/docs/mcp/server), cztery narzędzia i ich schematy
- [Gotowe scenariusze MCP](https://foura.ai/docs/mcp/recipes), prompty workflow dostarczane z serwerem
- [Błędy API](https://foura.ai/docs/api/errors), ta sama powłoka na bazowej warstwie REST API
- [Rate limity](https://foura.ai/docs/api/rate-limits), limity konta i platformy stojące za `rate_limited` i `at_capacity`
