# Erreurs du serveur MCP

> URL: https://foura.ai/fr/docs/mcp/errors
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

Comment gérer les erreurs renvoyées par le [foura-mcp server](https://foura.ai/docs/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 :

```json
{
  "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](https://foura.ai/docs/api/errors) 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`](https://foura.ai/docs/api/endpoints#browser-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)

```typescript
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](https://foura.ai/docs/mcp/server), les quatre outils et leurs schémas
- [Recettes MCP](https://foura.ai/docs/mcp/recipes), prompts de workflow fournis avec le serveur
- [Erreurs d'API](https://foura.ai/docs/api/errors), même enveloppe au niveau de la couche API REST sous-jacente
- [Rate limits](https://foura.ai/docs/api/rate-limits), les limites de compte et de plateforme derrière `rate_limited` et `at_capacity`
