# MCP-Server-Fehler

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

So behandelst du Fehler, die vom [foura-mcp server](https://foura.ai/docs/mcp/server) zurückgegeben werden.

Jede Fehlerantwort aller vier Tools (`foura_auto`, `foura_single`, `foura_proxy`, `foura_browser`) ist strukturiert. LLM-Agents können das Feld `code` für Retry-Logik auslesen, ohne Fließtext parsen zu müssen.

## Envelope-Struktur

Jeder Fehler (`isError: true`) enthält einen `structuredContent`-Block. Mindestfelder bei jedem Fehler:

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

Bei Upstream-Fehlern mit HTTP-Status ist auch `status` vorhanden. Wenn das geteilte Kontingent der Plattform einen Aufruf ablehnt, ergänzt der Envelope `retryAfter`, `current.{concurrency, rpm}` und `limits.{maxConcurrency, maxRpm}` im selben Format wie die zugrunde liegenden [REST-API-Fehler](https://foura.ai/docs/api/errors).

Wenn ein Limit deines eigenen Tarifs einen Aufruf ablehnt, entspricht der Code genau diesem Limit: `plan_limit_` gefolgt von `credits`, `bandwidth`, `rate`, `concurrency`, `browser_daily`, `premium` oder `feature`. `retryAfter` gibt die Wartezeit an, falls Abwarten das Problem behebt. Das Feld fehlt bei Limits, die sich durch Warten nicht beheben lassen, wie etwa bei einem im Tarif nicht enthaltenen Feature. `plan_limit_browser_daily` enthält ebenfalls kein `retryAfter`: Es wird um Mitternacht UTC zurückgesetzt. `plan_limit_credits` und `plan_limit_bandwidth` begrenzen `retryAfter` auf 24 Stunden und ergänzen `resets_at`, das genaue Ende des Abrechnungszeitraums. Lies daher `resets_at`, bevor du einen Retry planst.

Auf `foura_auto` wird ein innerhalb der Stufenleiter erreichtes Tariflimit als `rate_limited` oder `forbidden` zurückgegeben, mit dem Code des Tarifs in `reason`.

## Stabile `code`-Werte

| Code | HTTP | Bedeutung | Retry sicher? |
|---|---|---|---|
| `ssrf_blocked` | n/a | Das Ziel ist eine private oder reservierte Adresse (RFC 5735, RFC 6598, IPv6-reserviert), die URL ist nicht http(s) oder der Hostname konnte nicht aufgelöst werden | Nein, prüfe die URL. Ein kurzzeitig fehlgeschlagener Lookup kann wiederholt werden |
| `upstream_non_json` | variiert | Upstream hat einen Body zurückgegeben, der kein gültiges JSON war | Vielleicht, untersuchen |
| `output_validation_failed` | n/a | `outputSchema` des MCP-Servers hat die Upstream-Antwort abgelehnt oder das Tool konnte den Aufruf gar nicht abschließen (kein API-Key konfiguriert, API nicht erreichbar) | Vielleicht: Setup prüfen, dann melden |
| `bad_request` | 400 | Eingabeformat von der FourA-API abgelehnt, die Ziel-URL verweist auf die eigene API von FourA statt auf eine Seite (dort kann nur `/inspect` abgerufen werden), die URL enthält ein nicht kodiertes Leerzeichen (kodiere es als `%20`) oder `proxy` benennt einen Exit, den der Aufruf nicht nutzen kann: Ein Premium-Exit nach Verbrauch deines Premium-Traffics antwortet mit `Managed exit: this proxy id cannot be pinned to a request`. Es wird nichts abgerufen oder berechnet | Nein, Argumente korrigieren |
| `auth_failed` | 401 | Der FourA-API-Key fehlt, ist ungültig oder deaktiviert; dies betrifft keine Anmeldedaten der Zielseite | Nein, FourA-Key korrigieren |
| `forbidden` | 403 | Das Ziel antwortete mit 403 und dein `validate` hat es abgelehnt (eine Seitenprüfung, eine Länderbeschränkung) | Nein, oder zu `foura_proxy` wechseln |
| `not_found` | 404 | Ziel-URL oder Endpoint existiert nicht | Nein |
| `rate_limited` | 429 | Das geteilte Minutenkontingent der Plattform oder ein 429 vom Ziel, das dein `validate` abgelehnt hat. Bei `foura_auto` können es auch die Credits deines Tarifs, Traffic oder das Rate Limit sein (siehe `reason`) | Ja, warte `retryAfter`, falls vorhanden, sonst Backoff nutzen |
| `at_capacity` | 503 | Limit für gleichzeitige Anfragen erreicht (`current.concurrency` > `limits.maxConcurrency`), oder der Dienst ist wegen Wartungsarbeiten abgeschaltet (`error` lautet `Service disabled`, `retryAfter` ist 60) | Ja, warte `retryAfter` Sekunden |
| `service_disabled` | 503 | Reserviert. Ein wegen Wartung abgeschalteter Dienst erscheint aktuell als `at_capacity`, und ein Tool, das dein Tarif nicht enthält, wird als `plan_limit_feature` zurückgegeben | Support kontaktieren |
| `service_unavailable` | 503 | Generischer 503 vom Upstream | Ja, kurzer Backoff |
| `upstream_error` | 500+ oder 0 | Das Ziel antwortete mit einem Serverfehler, oder bei `foura_proxy` haben `foura_browser` und `foura_auto` nie geantwortet | Ja, exponentieller Backoff |
| `upstream_client_error` | 4xx | Andere 4xx, die oben nicht abgedeckt sind | Meistens nein |
| `upstream_unknown` | andere | Der Request lief, lieferte aber keine akzeptierte Antwort: Bei `foura_single` hat das Ziel nie geantwortet (Timeout, Verbindung abgelehnt), und bei jedem Tool hat dein `validate` eine 2xx- oder 3xx-Antwort abgelehnt. Lies `status` und `error` | Untersuchen |
| `no_eligible_proxy` | n/a | Kein Proxy passt zur strikten `exitCountries` Allowlist; `details.exitCountries` enthält den normalisierten Scope | Später wiederholen; Scope nur explizit ändern |
| `plan_limit_credits` | 429 | Die monatlichen Credits deines Tarifs sind aufgebraucht | Ja, nach `retryAfter`, oder Tarif ändern |
| `plan_limit_bandwidth` | 429 | Das Traffic-Kontingent deines Tarifs ist für diesen Abrechnungszeitraum aufgebraucht | Ja, nach `retryAfter`, oder Tarif ändern |
| `plan_limit_rate` | 429 | Requests pro Minute deines Tarifs für diesen Endpoint | Ja, nach `retryAfter` |
| `plan_limit_concurrency` | 429 | Gleichzeitige Requests deines Tarifs für diesen Endpoint | Ja, nach `retryAfter` |
| `plan_limit_browser_daily` | 429 | Das tägliche Browser-Kontingent deines Tarifs ist aufgebraucht | Ja, morgen, oder nutze `foura_single` / `foura_proxy` |
| `plan_limit_premium` | 403 | Du hast `exitClass: "premium"` mit einem Tarif gesendet, der keine Premium-Exits enthält | Nein, Parameter weglassen oder Tarif ändern |
| `plan_limit_feature` | 403 | Der Tarif enthält diesen Endpoint oder diese Funktion nicht | Nein, Tarif ändern |

## HTTP-Fehler vom MCP-Server

Manche Fehler treten auf MCP-Transportebene auf, bevor ein Tool aufgerufen wird. Diese liefern rohe JSON-RPC-Fehler (kein `structuredContent`):

| HTTP | Wann | Was du siehst |
|---|---|---|
| 400 | Nicht unterstützter `MCP-Protocol-Version`-Header | `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 | Ein Tool-Aufruf oder Ressourcen-Lesezugriff ohne API-Key. Das Auflisten von Tools und Prompts funktioniert ohne Key | JSON-RPC-Fehler + `WWW-Authenticate: Bearer realm="foura-mcp"` |
| 403 | Unzulässiger `Origin`- oder `Host`-Header (Schutz vor DNS-Rebinding, CVE-2025-66414) | `Origin <value> is not in the allowlist` oder `Host <value> is not in the allowlist` |
| 405 | `GET` oder `DELETE` auf `/mcp` (Stateless-Modus) | `Method not allowed in stateless mode. Use POST /mcp.` |
| 413 | Request-Body > 256 KB | Express-Standard 413 |

Die Allowlisten für 403 können beim Self-Hosting über `FOURA_MCP_ALLOWED_HOSTS` und `FOURA_MCP_ALLOWED_ORIGINS` per Umgebungsvariable konfiguriert werden.

## Abgelehnte Browser-Profile

Ein Browser-Profil, das der Katalog nicht bereitstellen kann, oder ein Profil mit `unblocker` auf `false`, wird als Upstream-Fehler zurückgegeben. Der Grund steht in `error` und der Request verlässt FourA nicht. Für eine nicht existierende Kombination aus `browser`, `os` und `version` nennt die Meldung verfügbare Alternativen. Wiederhole den Request mit einer der aufgelisteten Kombinationen statt mit derselben. Eine unbekannte `profile`-ID erhält `unknown profile` ohne Liste: Schlage die ID unter [`GET /api/profiles`](https://foura.ai/docs/api/endpoints#browser-profiles) nach.

Dies sind Ablehnungen, keine Ausfälle: Ein erneuter identischer Request kann nicht erfolgreich sein, und es wurde kein anderer Browser als Ersatz verwendet.

## Retry-Strategie

Fünf Kategorien:

- **Dein eigener Plan hat die Anfrage abgelehnt, nicht das Ziel**: jeder `plan_limit_*` Code. `plan_limit_credits` und `plan_limit_bandwidth` zählen für das gesamte Konto, daher wird dieselbe Arbeit über ein anderes Tool ebenfalls abgelehnt. `plan_limit_rate`, `plan_limit_concurrency`, `plan_limit_browser_daily` und `plan_limit_feature` gelten für einen einzelnen Endpoint, sodass ein anderes Tool weiterhin ausgeführt werden kann, falls es die Aufgabe erledigen kann. Warte `retryAfter` ab, falls vorhanden; andernfalls muss der Plan geändert werden. `plan_limit_premium` kannst du selbst beheben, indem du `exitClass` weglässt.
- **Warten und wiederholen**: `rate_limited`, `at_capacity`, `service_unavailable`, `upstream_error`. Berücksichtige `retryAfter`, falls vorhanden. Nutze exponentielles Backoff mit Jitter, wenn es fehlt. Reagiere nicht darauf, indem du alle eingereihten Tool-Aufrufe sofort erneut sendest: Reduziere stattdessen die Anzahl paralleler Ausführungen.
- **Scope beibehalten und später wiederholen**: `no_eligible_proxy`. Entferne `exitCountries` nicht und ersetze es nicht stillschweigend durch ein anderes Land. Ändere oder erweitere die Allowlist nur, wenn der Nutzer die Anforderung explizit anpasst.
- **Nicht wiederholen, bis Eingabe oder Anmeldedaten korrigiert sind**: `bad_request`, `auth_failed`, `not_found`, `ssrf_blocked`. Überprüfe bei `auth_failed` den FourA-API-Key, nicht die Anmeldedaten der Zielseite.
- **Tool wechseln, wenn der Inhalt es erfordert**: `forbidden` bei `foura_single` kann einen begrenzten `foura_proxy` Versuch rechtfertigen. Verwende `foura_browser`, wenn der gewünschte Inhalt JavaScript benötigt. Übergib nach einer erfolgreichen Proxy-Auswahl die zurückgegebene `proxy` ID an `foura_browser.proxy`, statt eine neue Auswahl zu starten.

## Retry-Beispiel (TypeScript, MCP-seitig)

```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");
}
```

## Verwandte Themen

- [MCP Server](https://foura.ai/docs/mcp/server), die vier Tools und ihre Schemas
- [MCP Recipes](https://foura.ai/docs/mcp/recipes), mit dem Server gelieferte Workflow-Prompts
- [API Errors](https://foura.ai/docs/api/errors), identischer Envelope auf der zugrunde liegenden REST-API-Ebene
- [Rate Limits](https://foura.ai/docs/api/rate-limits), die Account- und Plattform-Limits hinter `rate_limited` und `at_capacity`
