MCP-Server-Fehler

So behandelst du Fehler, die vom foura-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:

{
  "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.

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

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");
}
  • MCP Server, die vier Tools und ihre Schemas
  • MCP Recipes, mit dem Server gelieferte Workflow-Prompts
  • API Errors, identischer Envelope auf der zugrunde liegenden REST-API-Ebene
  • Rate Limits, die Account- und Plattform-Limits hinter rate_limited und at_capacity
Aktualisiert: 13. November 2026