Erreurs du serveur MCP

Comment gérer les erreurs renvoyées par le foura-mcp server.

Chaque réponse d'erreur provenant de l'un des quatre outils (foura_auto, foura_single, foura_proxy, foura_browser) est structurée. Les agents LLM peuvent lire le champ code pour leur logique de nouvelle tentative sans avoir à analyser de texte brut.

Structure de l'enveloppe

Chaque erreur (isError: true) contient un bloc structuredContent. Champs minimaux présents sur chaque erreur :

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

En cas d'erreurs en amont avec un statut HTTP, status est également présent. Lorsque le quota partagé de la plateforme refuse un appel, l'enveloppe ajoute retryAfter, current.{concurrency, rpm} et limits.{maxConcurrency, maxRpm}, selon la même structure que les erreurs de l'API REST sous-jacente.

Lorsqu'une des limites propres à votre forfait refuse un appel, le code correspond directement à cette limite : plan_limit_ suivi de credits, bandwidth, rate, concurrency, browser_daily, premium ou feature. retryAfter indique le temps d'attente lorsqu'une attente permet de débloquer la situation, et est absent pour une limite qu'une attente ne peut pas résoudre, comme une fonctionnalité non incluse dans le forfait. plan_limit_browser_daily ne comporte pas non plus de retryAfter : il se réinitialise à minuit UTC. plan_limit_credits et plan_limit_bandwidth plafonnent retryAfter à 24 heures et ajoutent resets_at, la fin exacte de la période de facturation, lisez donc resets_at avant de planifier une nouvelle tentative.

Sur foura_auto, une limite de forfait atteinte dans sa hiérarchie est renvoyée sous la forme rate_limited ou forbidden, avec le code du forfait dans reason.

Valeurs code stables

Code HTTP Signification Nouvelle tentative sans risque ?
ssrf_blocked n/a La cible est une adresse privée ou réservée (RFC 5735, RFC 6598, IPv6 réservée), l'URL n'est pas http(s), ou son nom d'hôte n'a pas pu être résolu Non, vérifiez l'URL. Une résolution ayant échoué brièvement peut être retentée
upstream_non_json varie L'amont a renvoyé un corps qui n'était pas un JSON valide Peut-être, à analyser
output_validation_failed n/a Le outputSchema du serveur MCP a rejeté la réponse en amont, ou l'outil n'a pas pu terminer l'appel (aucune clé API configurée, API inaccessible) Peut-être : vérifiez la configuration, puis signalez le problème
bad_request 400 Format d'entrée rejeté par l'API FourA, l'URL cible pointe vers la propre API de FourA au lieu d'une page (seul /inspect peut y être récupéré), l'URL contient un espace non encodé (encodez-le sous la forme %20), ou proxy indique une sortie que l'appel ne peut pas utiliser : une sortie premium après épuisement de votre trafic premium renvoie Managed exit: this proxy id cannot be pinned to a request. Rien n'est récupéré ni facturé Non, corrigez les arguments
auth_failed 401 La clé API FourA est manquante, invalide ou désactivée ; cela ne concerne pas les identifiants du site cible Non, corrigez la clé FourA
forbidden 403 La cible a répondu 403 et votre validate l'a rejetée (vérification du site, restriction géographique) Non, ou passez à foura_proxy
not_found 404 L'URL ou l'endpoint cible n'existe pas Non
rate_limited 429 Quota partagé par minute de la plateforme, ou code 429 de la cible rejeté par votre validate. Sur foura_auto, il peut également s'agir des crédits, du volume de trafic ou de la limite de débit de votre forfait (voir reason) Oui, attendez retryAfter s'il est présent, sinon appliquez un backoff
at_capacity 503 Limite de requêtes simultanées atteinte (current.concurrency > limits.maxConcurrency), ou service désactivé pour maintenance (error indique Service disabled, retryAfter vaut 60) Oui, attendez retryAfter secondes
service_disabled 503 Réservé. Un service désactivé pour maintenance renvoie actuellement at_capacity, et un outil non inclus dans votre forfait renvoie plan_limit_feature Contactez le support
service_unavailable 503 503 générique provenant de l'amont Oui, court backoff
upstream_error 500+ ou 0 La cible a répondu avec une erreur serveur, ou sur foura_proxy, foura_browser et foura_auto n'ont jamais répondu Oui, backoff exponentiel
upstream_client_error 4xx Autre erreur 4xx non mentionnée ci-dessus Généralement non
upstream_unknown autre La requête a été exécutée mais n'a produit aucune réponse acceptée : sur foura_single la cible n'a jamais répondu (délai dépassé, connexion refusée), et sur n'importe quel outil votre validate a rejeté une réponse 2xx ou 3xx. Consultez status et error À analyser
no_eligible_proxy n/a Aucun proxy ne correspond à la liste d'autorisation stricte exitCountries ; details.exitCountries contient la portée normalisée Réessayez plus tard ; ne modifiez la portée que de manière explicite
plan_limit_credits 429 Les crédits mensuels de votre forfait sont épuisés Oui, après retryAfter, ou changez de forfait
plan_limit_bandwidth 429 Le volume de trafic alloué à votre forfait est épuisé pour cette période de facturation Oui, après retryAfter, ou changez de forfait
plan_limit_rate 429 Limite de requêtes par minute de votre forfait pour cet endpoint Oui, après retryAfter
plan_limit_concurrency 429 Limite de requêtes simultanées de votre forfait pour cet endpoint Oui, après retryAfter
plan_limit_browser_daily 429 Le quota quotidien de Browser de votre forfait est épuisé Oui, demain, ou utilisez foura_single / foura_proxy
plan_limit_premium 403 Vous avez envoyé exitClass: "premium" avec un forfait qui n'inclut pas les sorties premium Non, supprimez le paramètre ou changez de forfait
plan_limit_feature 403 Le forfait n'inclut pas cet endpoint ou cette fonctionnalité Non, changez de forfait

Erreurs de niveau HTTP du serveur MCP

Certains échecs surviennent au niveau de la couche de transport MCP, avant même l'appel d'un outil. Ceux-ci renvoient des erreurs JSON-RPC brutes (pas de structuredContent) :

HTTP Circonstance Ce que vous voyez
400 Header MCP-Protocol-Version non pris en charge 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 Appel d'un outil ou lecture d'une ressource sans clé API. Le listing des outils et des prompts fonctionne sans clé Erreur JSON-RPC + WWW-Authenticate: Bearer realm="foura-mcp"
403 Header Origin ou Host non autorisé (protection contre le DNS-rebinding, CVE-2025-66414) Origin <value> is not in the allowlist ou Host <value> is not in the allowlist
405 GET ou DELETE sur /mcp (mode sans état) Method not allowed in stateless mode. Use POST /mcp.
413 Corps de la requête > 256 Ko Erreur 413 par défaut d'Express

Les listes d'autorisation pour les erreurs 403 sont configurables via des variables d'environnement pour l'auto-hébergement avec FOURA_MCP_ALLOWED_HOSTS et FOURA_MCP_ALLOWED_ORIGINS.

Profils de navigateur refusés

Un profil de navigateur que le catalogue ne peut pas fournir, ou un profil envoyé avec unblocker défini sur false, renvoie une erreur en amont avec la raison indiquée dans error et la requête ne quitte jamais FourA. Pour une combinaison de browser, os et version qui n'existe pas, le message indique ce qui est disponible, réessayez donc avec l'une des combinaisons listées plutôt qu'avec la même. Un identifiant profile inconnu renvoie unknown profile sans liste : recherchez l'identifiant sur GET /api/profiles.

Il s'agit de refus, non de pannes : réitérer la requête identique ne peut pas aboutir, et aucun autre navigateur n'a été utilisé à la place.

Stratégie de nouvelle tentative

Cinq catégories :

  • Votre propre forfait l'a refusé, pas la cible : tout code plan_limit_*. plan_limit_credits et plan_limit_bandwidth prennent en compte l'ensemble du compte, donc le même travail via un autre outil sera également refusé. plan_limit_rate, plan_limit_concurrency, plan_limit_browser_daily et plan_limit_feature s'appliquent à un seul endpoint, un autre outil peut donc toujours s'exécuter s'il peut effectuer la tâche. Attendez l'expiration de retryAfter lorsqu'il est présent ; sinon, le forfait doit être modifié. plan_limit_premium est celui que vous pouvez régler vous-même, en supprimant exitClass.
  • Attendez et réessayez : rate_limited, at_capacity, service_unavailable, upstream_error. Respectez retryAfter lorsqu'il est présent. Utilisez un backoff exponentiel avec gigue lorsqu'il est absent. N'y répondez pas en relançant simultanément tous les appels d'outils en file d'attente : réduisez plutôt le nombre d'appels exécutés en parallèle.
  • Préservez le périmètre et réessayez plus tard : no_eligible_proxy. Ne supprimez pas exitCountries et ne le remplacez pas silencieusement par un autre pays. Modifiez ou élargissez la liste d'autorisation uniquement lorsque l'utilisateur modifie explicitement les exigences.
  • Ne réessayez pas tant que l'entrée ou les identifiants ne sont pas corrigés : bad_request, auth_failed, not_found, ssrf_blocked. Pour auth_failed, vérifiez la clé API FourA, pas les identifiants du site cible.
  • Changez d'outil lorsque le contenu l'exige : forbidden sur foura_single peut justifier une tentative foura_proxy limitée. Utilisez foura_browser lorsque le contenu souhaité nécessite JavaScript. Après une sélection de proxy réussie, transmettez l'ID proxy renvoyé à foura_browser.proxy au lieu de lancer une nouvelle sélection.

Exemple de nouvelle tentative (TypeScript, côté MCP)

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");
}
  • Serveur MCP, les quatre outils et leurs schémas
  • Recettes MCP, prompts de workflow fournis avec le serveur
  • Erreurs d'API, même enveloppe au niveau de la couche API REST sous-jacente
  • Rate limits, les limites de compte et de plateforme derrière rate_limited et at_capacity
Mis à jour : 13 novembre 2026