Errores del servidor MCP

Cómo manejar los errores devueltos por el servidor foura-mcp.

Cada respuesta de error de cualquiera de las cuatro herramientas (foura_auto, foura_single, foura_proxy, foura_browser) está estructurada. Los agentes LLM pueden leer el campo code para la lógica de reintento sin necesidad de analizar texto libre.

Estructura del envelope

Cada error (isError: true) incluye un bloque structuredContent. Campos mínimos en cada error:

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

En errores de upstream con estado HTTP, status también está presente. Cuando la cuota compartida de la plataforma rechaza una llamada, el sobre añade retryAfter, current.{concurrency, rpm} y limits.{maxConcurrency, maxRpm}, con la misma estructura que los errores subyacentes de la API REST.

Cuando uno de los límites propios de tu plan rechaza una llamada, el código ES ese límite: plan_limit_ seguido de credits, bandwidth, rate, concurrency, browser_daily, premium o feature. retryAfter indica el tiempo de espera cuando esperar lo soluciona, y está ausente en límites que una espera no puede restablecer, como una función no incluida en el plan. plan_limit_browser_daily tampoco incluye retryAfter: se restablece a medianoche UTC.

En foura_auto, un límite del plan alcanzado dentro de su escala se devuelve como rate_limited o forbidden, con el código del plan en reason.

Valores estables de code

Errores a nivel HTTP del servidor MCP

Algunos fallos ocurren en la capa de transporte de MCP, antes de que se llame a cualquier tool. Estos devuelven errores JSON-RPC puros (sin structuredContent):

Las listas de permitidos para 403 se pueden configurar mediante variables de entorno para implementaciones self-hosted a través de FOURA_MCP_ALLOWED_HOSTS y FOURA_MCP_ALLOWED_ORIGINS.

Perfiles de navegador rechazados

Un perfil de navegador que el catálogo no puede ofrecer, o un perfil enviado con unblocker establecido en false, se devuelve como un fallo upstream con el motivo en error y la request nunca sale de FourA. El mensaje indica lo que está disponible, así que reintenta con una de las combinaciones listadas en lugar de usar la misma.

Estos son rechazos, no interrupciones del servicio: reintentar la request idéntica no puede tener éxito y no se utilizó ningún otro navegador en su lugar.

Estrategia de reintento

Cinco categorías:

• Tu propio plan lo rechazó, no el objetivo: cualquier código plan_limit_*. El mismo trabajo a través de otra tool también será rechazado, por lo que cambiar de endpoint solo consume tiempo. Espera a que termine retryAfter cuando exista uno; de lo contrario, el plan debe cambiar. plan_limit_premium es el que puedes solucionar tú mismo, eliminando exitClass.
• Esperar y reintentar: rate_limited, at_capacity, service_unavailable, upstream_error. Respeta retryAfter cuando esté presente. Usa backoff exponencial con jitter cuando no esté disponible. No respondas reenviando todas las llamadas a tools en cola a la vez: reduce en su lugar cuántas ejecutas en paralelo.
• Conservar el alcance y reintentar más tarde: no_eligible_proxy. No elimines exitCountries ni sustituyas otro país silenciosamente. Modifica o amplía la lista de permitidos únicamente cuando el usuario cambie el requisito de forma explícita.
• No reintentar hasta que se corrija la entrada o la credencial: bad_request, auth_failed, not_found, ssrf_blocked. Para auth_failed, verifica la API key de FourA, no las credenciales del sitio objetivo.
• Cambiar de tool cuando el contenido lo requiera: forbidden en foura_single puede justificar un intento acotado de foura_proxy. Usa foura_browser cuando el contenido deseado necesite JavaScript. Tras una selección de proxy exitosa, pasa el ID proxy devuelto a foura_browser.proxy en lugar de iniciar una nueva selección.

Ejemplo de reintento (TypeScript, lado de 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");
}

Relacionado

• MCP Server, las cuatro herramientas y sus esquemas
• MCP Recipes, prompts de flujo de trabajo incluidos con el servidor
• API Errors, la misma estructura en la capa de la REST API subyacente
• Rate Limits, los límites de cuenta y plataforma detrás de rate_limited y at_capacity