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_creditsundplan_limit_bandwidthzä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_dailyundplan_limit_featuregelten für einen einzelnen Endpoint, sodass ein anderes Tool weiterhin ausgeführt werden kann, falls es die Aufgabe erledigen kann. WarteretryAfterab, falls vorhanden; andernfalls muss der Plan geändert werden.plan_limit_premiumkannst du selbst beheben, indem duexitClassweglässt. - Warten und wiederholen:
rate_limited,at_capacity,service_unavailable,upstream_error. BerücksichtigeretryAfter, 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. EntferneexitCountriesnicht 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 beiauth_failedden FourA-API-Key, nicht die Anmeldedaten der Zielseite. - Tool wechseln, wenn der Inhalt es erfordert:
forbiddenbeifoura_singlekann einen begrenztenfoura_proxyVersuch rechtfertigen. Verwendefoura_browser, wenn der gewünschte Inhalt JavaScript benötigt. Übergib nach einer erfolgreichen Proxy-Auswahl die zurückgegebeneproxyID anfoura_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 gelieferte Workflow-Prompts
- API Errors, identischer Envelope auf der zugrunde liegenden REST-API-Ebene
- Rate Limits, die Account- und Plattform-Limits hinter
rate_limitedundat_capacity