MCP-Server-Fehler

So behandelst du Fehler, die vom foura-mcp server zurückgegeben werden.

Jede Fehler-Response von einem der vier Tools (foura_auto, foura_single, foura_proxy, foura_browser) ist strukturiert. LLM-Agents können das code-Feld 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 status ebenfalls vorhanden. Wenn das geteilte Kontingent der Plattform einen Aufruf ablehnt, enthält der Envelope zusätzlich retryAfter, current.{concurrency, rpm} und limits.{maxConcurrency, maxRpm}, im selben Format wie die zugrundeliegenden REST-API-Fehler.

Wenn eines der Limits 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 enthält die Wartezeit, sofern Warten das Problem behebt, und fehlt bei Limits, die sich nicht durch Warten lösen lassen, wie etwa ein im Tarif nicht enthaltenes Feature. plan_limit_browser_daily enthält ebenfalls kein retryAfter: Es wird um Mitternacht UTC zurückgesetzt.

Bei foura_auto wird ein Tariflimit innerhalb seiner Stufe als rate_limited oder forbidden zurückgegeben, mit dem Tarif-Code in reason.

Stabile code-Werte

HTTP-Fehler vom MCP-Server

Manche Fehler treten auf der MCP-Transportschicht auf, bevor ein Tool aufgerufen wird. Diese geben reine JSON-RPC-Fehler zurück (kein structuredContent):

Die Allowlists für 403 sind für Self-Hoster über FOURA_MCP_ALLOWED_HOSTS und FOURA_MCP_ALLOWED_ORIGINS per Umgebungsvariable konfigurierbar.

Abgelehnte Browser-Profile

Ein Browser-Profil, das der Katalog nicht bereitstellen kann, oder ein Profil, das mit unblocker auf false gesendet wurde, wird als Upstream-Fehler mit dem Grund in error zurückgegeben und der Request verlässt FourA nie. Die Meldung nennt verfügbare Optionen. Wiederhole den Versuch mit einer der aufgelisteten Kombinationen statt mit derselben.

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 abgelehnt, nicht das Ziel: Jeder plan_limit_* Code. Dieselbe Aktion über ein anderes Tool wird ebenfalls abgelehnt, ein Wechsel der Endpoints kostet also nur Zeit. Warte retryAfter ab, falls vorhanden; andernfalls muss der Plan geändert werden. plan_limit_premium kannst du selbst beheben, indem du exitClass entfernst.
• Warten und wiederholen: rate_limited, at_capacity, service_unavailable, upstream_error. Beachte retryAfter, falls vorhanden. Nutze Exponential Backoff mit Jitter, wenn kein Wert vorliegt. Reagiere nicht damit, alle anstehenden Tool-Aufrufe sofort erneut zu senden: Reduziere stattdessen die Anzahl paralleler Requests.
• Scope beibehalten und später wiederholen: no_eligible_proxy. Entferne exitCountries nicht und ersetze Länder nicht stillschweigend. Ändere oder erweitere die Allowlist nur, wenn der Nutzer die Anforderung explizit anpasst.
• Nicht wiederholen, bis Input oder Zugangsdaten korrigiert sind: bad_request, auth_failed, not_found, ssrf_blocked. Prüfe bei auth_failed den FourA API key, nicht die Zugangsdaten der Zielseite.
• Tool wechseln, wenn der Inhalt es erfordert: forbidden auf foura_single kann einen begrenzten Versuch mit foura_proxy rechtfertigen. Nutze foura_browser, wenn der gewünschte Inhalt JavaScript benötigt. Übergib nach erfolgreicher 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");
}

Verwandte Themen

• MCP Server, die vier Tools und ihre Schemas
• MCP Recipes, mit dem Server ausgelieferte Workflow-Prompts
• API Errors, dieselbe Envelope auf der zugrunde liegenden REST-API-Ebene
• Rate Limits, die Account- und Plattform-Limits hinter rate_limited und at_capacity