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_creditsyplan_limit_bandwidthcontabilizan 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_dailyyplan_limit_featurese aplican a un solo endpoint, por lo que otra herramienta aún puede ejecutarse si esa herramienta puede hacer el trabajo. Espera a que termineretryAftersi existe uno; de lo contrario, el plan debe cambiar.plan_limit_premiumes el único que puedes solucionar tú mismo, eliminandoexitClass. - Espera y reintenta:
rate_limited,at_capacity,service_unavailable,upstream_error. RespetaretryAftercuando 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 eliminesexitCountriesni 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. Paraauth_failed, verifica la API key de FourA, no las credenciales del sitio de destino. - Cambia de herramienta cuando el contenido lo requiera:
forbiddenenfoura_singlepuede justificar un intento acotado defoura_proxy. Usafoura_browsercuando el contenido deseado requiera JavaScript. Tras una selección de proxy exitosa, pasa el IDproxydevuelto afoura_browser.proxyen 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 subyacente de la REST API
- Rate Limits, los límites de cuenta y plataforma detrás de
rate_limitedyat_capacity