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 prosa.

Estructura del contenedor

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 REST API.

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 incluye el tiempo de espera cuando una espera lo soluciona, y está ausente para un límite que una espera no puede resolver, como una funcionalidad que el plan no incluye. plan_limit_browser_daily tampoco incluye retryAfter: se restablece a medianoche UTC. plan_limit_credits y plan_limit_bandwidth limitan retryAfter a 24 horas y añaden resets_at, el final exacto del periodo de facturación, así que lee resets_at antes de programar un reintento.

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

Valores code estables

Código HTTP Significado ¿Seguro reintentar?
ssrf_blocked n/a El destino es una dirección privada o reservada (RFC 5735, RFC 6598, IPv6 reservada), la URL no es http(s) o su nombre de host no se resolvió No, comprueba la URL. Una resolución que falló brevemente se puede reintentar
upstream_non_json varía El upstream devolvió un cuerpo que no era JSON válido Quizás, investigar
output_validation_failed n/a El outputSchema del servidor MCP rechazó la respuesta del upstream, o la herramienta no pudo completar la llamada en absoluto (no hay API key configurada, API inaccesible) Quizás: comprueba la configuración, luego reporta
bad_request 400 Estructura de entrada rechazada por la API de FourA, la URL de destino apunta a la propia API de FourA en lugar de a una página (solo /inspect se puede obtener allí), la URL tiene un espacio sin codificar dentro (codifícalo como %20), o proxy indica una salida que la llamada no puede usar: una salida premium una vez agotado tu tráfico premium responde Managed exit: this proxy id cannot be pinned to a request. No se obtiene ni se cobra nada No, corrige los argumentos
auth_failed 401 La API key de FourA falta, no es válida o está desactivada; esto no está relacionado con las credenciales del sitio de destino No, corrige la clave de FourA
forbidden 403 El destino respondió 403 y tu validate lo rechazó (una comprobación del sitio, una restricción por país) No, o cambia a foura_proxy
not_found 404 La URL de destino o el endpoint no existen No
rate_limited 429 El límite compartido por minuto de la plataforma, o un 429 del destino que tu validate rechazó. En foura_auto también pueden ser los créditos, el tráfico o el rate limit de tu plan (consulta reason) Sí, espera retryAfter cuando esté presente, de lo contrario aplica backoff
at_capacity 503 Límite de concurrencia alcanzado (current.concurrency > limits.maxConcurrency), o el servicio está desactivado por mantenimiento (error indica Service disabled, retryAfter es 60) Sí, espera retryAfter segundos
service_disabled 503 Reservado. Un servicio desactivado por mantenimiento llega hoy como at_capacity, y una herramienta que tu plan no incluye se devuelve como plan_limit_feature Contacta con soporte
service_unavailable 503 503 genérico del upstream Sí, backoff corto
upstream_error 500+ o 0 El destino respondió con un error de servidor, o en foura_proxy, foura_browser y foura_auto nunca respondieron Sí, backoff exponencial
upstream_client_error 4xx Otro 4xx no cubierto arriba Normalmente no
upstream_unknown otro La request se ejecutó pero no produjo una respuesta aceptada: en foura_single el destino nunca respondió (timeout, conexión rechazada), y en cualquier herramienta tu validate rechazó una respuesta 2xx o 3xx. Lee status y error Investigar
no_eligible_proxy n/a Ningún proxy coincide con la allowlist estricta exitCountries; details.exitCountries contiene el scope normalizado Reintenta más tarde; cambia el scope solo de forma explícita
plan_limit_credits 429 Los créditos mensuales de tu plan se han agotado Sí, después de retryAfter, o cambia de plan
plan_limit_bandwidth 429 El límite de tráfico de tu plan se ha agotado para este periodo de facturación Sí, después de retryAfter, o cambia de plan
plan_limit_rate 429 Requests por minuto de tu plan para ese endpoint Sí, después de retryAfter
plan_limit_concurrency 429 Requests simultáneas de tu plan para ese endpoint Sí, después de retryAfter
plan_limit_browser_daily 429 El límite diario de Browser de tu plan se ha agotado Sí, mañana, o usa foura_single / foura_proxy
plan_limit_premium 403 Enviaste exitClass: "premium" en un plan que no incluye salidas premium No, elimina el parámetro o cambia de plan
plan_limit_feature 403 El plan no incluye ese endpoint o esa funcionalidad No, cambia de plan

Errores a nivel HTTP del servidor MCP

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

HTTP Cuándo Lo que ves
400 Header MCP-Protocol-Version no soportado 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 Una llamada a una tool o lectura de recurso sin API key. Listar tools y prompts funciona sin ella Error JSON-RPC + WWW-Authenticate: Bearer realm="foura-mcp"
403 Header Origin o Host no permitido (defensa contra DNS-rebinding, CVE-2025-66414) Origin <value> is not in the allowlist o Host <value> is not in the allowlist
405 GET o DELETE en /mcp (modo stateless) Method not allowed in stateless mode. Use POST /mcp.
413 Cuerpo de la request > 256 KB 413 predeterminado de Express

Las listas de permitidos para el 403 son configurables por variables de entorno para self-hosters mediante 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 de upstream con el motivo en error y la request nunca sale de FourA. Para una combinación de browser, os y version que no existe, el mensaje indica qué está disponible, así que reintenta con una de las combinaciones listadas en lugar de con la misma. Un id de profile desconocido recibe unknown profile sin lista: busca el id en GET /api/profiles.

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

Estrategia de reintentos

Cinco categorías:

  • Tu propio plan lo rechazó, no el destino: cualquier código plan_limit_*. plan_limit_credits y plan_limit_bandwidth contabilizan toda la cuenta, por lo que el mismo trabajo mediante otra herramienta también será rechazado. plan_limit_rate, plan_limit_concurrency, plan_limit_browser_daily y plan_limit_feature se aplican a un solo endpoint, por lo que otra herramienta aún puede ejecutarse si esa herramienta puede hacer el trabajo. Espera a que termine retryAfter si existe uno; de lo contrario, el plan debe cambiar. plan_limit_premium es el único que puedes solucionar tú mismo, eliminando exitClass.
  • Espera y reintenta: rate_limited, at_capacity, service_unavailable, upstream_error. Respeta retryAfter cuando esté presente. Usa backoff exponencial con jitter cuando no esté disponible. No respondas reemitiendo todas las llamadas a herramientas en cola a la vez: reduce en su lugar cuántas ejecutas en paralelo.
  • Conserva el alcance y reintenta más tarde: no_eligible_proxy. No elimines exitCountries ni sustituyas otro país de forma silenciosa. Modifica o amplía la allowlist solo cuando el usuario cambie explícitamente el requisito.
  • No reintentes hasta corregir 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 de destino.
  • Cambia de herramienta cuando el contenido lo requiera: forbidden en foura_single puede justificar un intento acotado de foura_proxy. Usa foura_browser cuando el contenido deseado requiera 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");
}
  • 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 subyacente de la REST API
  • Rate Limits, los límites de cuenta y plataforma detrás de rate_limited y at_capacity
Actualizado: 13 de noviembre de 2026