Erreurs du serveur MCP

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

Chaque réponse d'erreur 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 la logique de nouvelle tentative sans 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"
}

Lors 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 le même format que les erreurs de l'API REST sous-jacentes.

Lorsque l'une des limites propres à votre forfait refuse un appel, le code EST 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 la débloquer, et est absent pour une limite qu'une attente ne peut pas débloquer, comme une fonctionnalité non incluse dans le forfait. plan_limit_browser_daily ne comporte pas non plus de retryAfter : elle se réinitialise à minuit UTC.

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 stables de code

Erreurs de niveau HTTP provenant du serveur MCP

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

Les listes d'autorisation pour le code 403 sont configurables par variables d'environnement pour les auto-hébergeurs via 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, est renvoyé comme un échec en amont avec la raison dans error et la requête ne quitte jamais FourA. Le message précise les options disponibles ; réessayez donc avec l'une des combinaisons listées plutôt qu'avec la même.

Il s'agit de refus et non d'interruptions de service : réessayer la requête identique ne peut pas réussir, et aucun autre navigateur n'a été utilisé à la place.

Stratégie de nouvelle tentative

Cinq catégories :

• Votre propre plan l'a refusé, pas la cible : tout code plan_limit_*. La même opération via un autre outil sera également refusée ; changer d'endpoint ne fait donc que perdre du temps. Patientez jusqu'à l'expiration de retryAfter s'il existe ; sinon, le plan doit être modifié. Le code plan_limit_premium est le seul que vous pouvez résoudre vous-même en retirant exitClass.
• Attendre et réessayer : rate_limited, at_capacity, service_unavailable, upstream_error. Respectez retryAfter lorsqu'il est présent. Utilisez un backoff exponentiel avec gigue en son absence. Ne répondez pas en relançant simultanément tous les appels d'outils en file d'attente : réduisez plutôt le nombre d'exécutions en parallèle.
• Conserver le périmètre et réessayer plus tard : no_eligible_proxy. Ne supprimez pas exitCountries et ne substituez pas un autre pays de manière silencieuse. Modifiez ou élargissez la liste d'autorisation uniquement si l'utilisateur modifie explicitement cette exigence.
• Ne pas réessayer avant d'avoir corrigé la saisie ou l'identifiant : bad_request, auth_failed, not_found, ssrf_blocked. Pour auth_failed, vérifiez la clé API FourA, pas les identifiants du site cible.
• Changer d'outil lorsque le contenu l'exige : forbidden sur foura_single peut justifier une tentative limitée avec foura_proxy. Utilisez foura_browser lorsque le contenu visé nécessite JavaScript. Après une sélection de proxy réussie, transmettez l'ID proxy renvoyé dans foura_browser.proxy au lieu de relancer 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");
}

Voir aussi

• Serveur MCP, les quatre outils et leurs schémas
• Recettes MCP, prompts de workflow fournis avec le serveur
• Erreurs API, même structure au niveau de l'API REST sous-jacente
• Limites de débit, les limites de compte et de plateforme derrière rate_limited et at_capacity