Errores, límites y correlación

Las cuatro capas en las que puede volver un fallo, cada código de error de las tools, los límites de admisión y cómo hacer trazable una llamada.

Una llamada al servidor MCP de Operator puede fallar en cuatro sitios. Revísalos en este orden.

1. HTTP y OAuth

La petición no llegó a ninguna tool.

Respuesta	Significado	Manéjalo
`401` + `WWW-Authenticate: Bearer …`	Token ausente, caducado o rechazado. El cuerpo es un error OAuth, no JSON-RPC.	Repite el descubrimiento OAuth desde el challenge. Nunca reintentes con credenciales improvisadas.
`403` + `insufficient_scope`	El token no lleva ninguno de los scopes de operator.	Vuelve a autorizar pidiendo `mcp:operator.read`.
`400` con JSON-RPC `-32022`	La petición no es MCP `2026-07-28` (por ejemplo, no lleva el sobre `_meta`). `data.supported` lista las revisiones que se sirven.	Usa un cliente que hable `2026-07-28`.
`400` con JSON-RPC `-32020`	La cabecera `Mcp-Method` o `Mcp-Name` falta o no coincide con el cuerpo.	Corrige las cabeceras.
`405`	Un `GET` o `DELETE` autenticado. El endpoint no guarda estado y solo acepta `POST`.	Envía `POST`.
`404`	No es un endpoint MCP.	Revisa la URL.
`500`	El servidor no pudo comprobar el token.	Reintenta tras una breve espera.

2. Errores JSON-RPC

La petición estaba bien formada, pero la llamada se rechazó antes de ejecutar la tool. Vuelven con HTTP 200 y un error JSON-RPC:

Código	Significado	Manéjalo
`-32602` (`InvalidParams`)	Nombre de tool desconocido, o argumentos que no cumplen el esquema de la tool: un argumento obligatorio ausente, uno de más o un valor fuera de rango.	Corrige la llamada. Repetirla sin cambios no puede funcionar.

3. Errores de tool

La tool se ejecutó y falló. El resultado lleva isError: true, y su contenido de texto es:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after the rate-limit window resets.",
    "retryable": true
  }
}

Muestra el mensaje y reintenta solo cuando retryable sea true.

`code`	Reintentable	Significado
`rate_limit_exceeded`	sí	Más de 120 llamadas por minuto a esta tool. Consulta límites de admisión.
`concurrency_limit_exceeded`	sí	Más de 12 llamadas en curso a esta tool.
`rate_limit_unavailable`, `concurrency_limit_unavailable`	sí	No se puede acceder al almacén de admisión. El servidor rechaza la llamada en lugar de admitirla sin control.
`forbidden`	no	La persona ya no es admin ni miembro de la organización.
`organization_scope_mismatch`	no	La llamada nombró una organización a la que el token no está ligado. Vuelve a autorizar para esa organización.
`invalid_organization_selector`	no	`organizationId` y `organizationSlug` nombran organizaciones distintas.
`organization_not_found`	no	Ninguna organización coincide con el selector.
`organization_required`	no	No se pudo resolver ninguna organización para la llamada.
`not_found`	no	El servicio de lectura de Vidext no encontró nada para la llamada.
`dependency_unavailable`	cuando el backend respondió `5xx`	El servicio de lectura de Vidext no pudo responder.
`invalid_dependency_response`	sí	El servicio de lectura de Vidext respondió algo que el servidor no pudo leer.
`internal_error`	sí	Cualquier otra cosa. El mensaje es genérico a propósito.

4. Fallos dentro del resultado en las tools de conocimiento

search_knowledge y read_knowledge_source informan de la mayoría de fallos dentro de un resultado normal, sin isError. Comprueba siempre success:

{ "success": false, "status": "unavailable", "reason": "timeout", "error": "Organization knowledge is unavailable right now." }

`status`	Tool	Significado	¿Reintentar?
`invalid`	las dos	Consulta vacía o demasiado vaga, o falta el handle.	No, corrige la entrada.
`unavailable`	las dos	No se pudo leer el conocimiento. `reason: "timeout"` cuando se agotó el plazo de 15 segundos.	Sí.
`rejected`	`read_knowledge_source`	El handle no salió de `search_knowledge` para esta organización, o ya no coincide con su fuente.	No, vuelve a buscar.
`missing`, `empty`	`read_knowledge_source`	La fuente, o su texto procesado, ya no está.	No.

Límites de admisión

Cada llamada a una tool cuenta por persona, organización y tool:

Límite	Valor
Tasa	120 llamadas por minuto (ventana deslizante)
Concurrencia	12 llamadas en curso

Una llamada rechazada vuelve como error de tool (rate_limit_exceeded o concurrency_limit_exceeded), no como HTTP 429. El endpoint MCP no envía 429, ni Retry-After, ni cabeceras RateLimit. Espera unos segundos y reintenta. Las llamadas rechazadas con InvalidParams no cuentan.

Si el almacén de admisión no está disponible, el servidor falla de forma cerrada con un error *_unavailable reintentable en lugar de ejecutar la llamada sin control.

El servidor MCP de documentación no tiene límites de admisión propios.

Límites en las rutas de OAuth y de registro

Estas rutas HTTP responden 429 cuando te pasas, y anuncian su cuota en cabeceras:

Ruta	Límite	Cabeceras
`/api/auth/*`	50 peticiones cada 10 segundos por defecto; las rutas de inicio de sesión, registro y código por email, 5 cada 5 minutos	`RateLimit-Policy` (por ejemplo `"auth";q=50;w=10`) y `RateLimit-Limit`: la cuota, no lo que queda. `Retry-After` en un rechazo.
`/api/agent/auth` y `/api/agent/auth/claim/complete`	60 registros y 30 completados por hora, por IP	Lo mismo, más la ventana en vivo: `RateLimit` (`limit=…, remaining=…, reset=…`), `RateLimit-Remaining`, `RateLimit-Reset`. `Retry-After` en cada `429`.

Los endpoints de autorización, token y consentimiento (/api/auth/oauth2/authorize, /token, /consent) no llevan estas cabeceras.

Correlación

Haz trazable cada llamada para que una petición de soporte se pueda cruzar con los registros de Vidext:

Envía una cabecera x-request-id con un valor único en cada POST, y guárdalo. Sin ella, el servidor genera la suya, que nunca ves.
Envía una cabecera W3C traceparent, o x-trace-id, para unir la llamada a tu propia traza.
Guarda el moduleId que pasaste.

Cuando una tool falla, Vidext registra el ID de petición, el ID de traza, la tool y el moduleId. Las respuestas no devuelven estas cabeceras. Para informar de un problema, envía el ID de petición, la hora, la tool y el code del error.

Errores, límites y correlación

1. HTTP y OAuthCopy Anchor Link

2. Errores JSON-RPCCopy Anchor Link

3. Errores de toolCopy Anchor Link

4. Fallos dentro del resultado en las tools de conocimientoCopy Anchor Link

Límites de admisiónCopy Anchor Link

Límites en las rutas de OAuth y de registroCopy Anchor Link

CorrelaciónCopy Anchor Link