# Errores del servidor MCP

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

Cómo manejar los errores devueltos por el servidor [foura-mcp](https://foura.ai/docs/mcp/server).

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:

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

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

```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");
}
```

## Relacionado

- [MCP Server](https://foura.ai/docs/mcp/server), las cuatro herramientas y sus esquemas
- [MCP Recipes](https://foura.ai/docs/mcp/recipes), prompts de flujo de trabajo incluidos con el servidor
- [API Errors](https://foura.ai/docs/api/errors), la misma estructura en la capa subyacente de la REST API
- [Rate Limits](https://foura.ai/docs/api/rate-limits), los límites de cuenta y plataforma detrás de `rate_limited` y `at_capacity`
