Errores
Los fallos llegan por dos canales distintos, y la diferencia importa: uno es una petición rota, el otro es algo que el modelo debe leer y a lo que debe reaccionar.
Errores de tool
Todo aquello sobre lo que el llamador puede actuar — validación, no encontrado, alcance insuficiente, permiso insuficiente, un error del endpoint — vuelve como una respuesta JSON-RPC exitosa cuyo resultado está marcado isError, llevando el envoltorio de error de la propia API como texto:
{ "jsonrpc": "2.0", "id": 2, "result": {
"isError": true,
"content": [{ "type": "text",
"text": "{ \"error\": { \"code\": \"NOT_FOUND\", \"message\": \"Portal user not found\" } }" }]
} }
El vocabulario de code es el de la API REST, sin cambios. Los que más vas a encontrar:
code | Cuándo |
|---|---|
VALIDATION_ERROR | Los argumentos fallaron la validación del endpoint; los detalles nombran los campos. |
NOT_FOUND | No existe ese registro, o pertenece a otra organización. |
CONFLICT / DUPLICATE_ERROR | external_id ya en uso, o una clave de negocio duplicada. |
BAD_REQUEST | Regla de negocio violada — por ejemplo, reenviar la invitación de un usuario del portal que ya está activo. |
FORBIDDEN | La operación no está permitida para este recurso en el estado en que está. |
EXTERNAL_SERVICE_ERROR | Un servicio externo del que depende la operación rechazó o no respondió. |
USER_DECLINED | En la era 2026-07-28, el usuario rechazó o canceló la confirmación de una tool destructiva. No se cambió nada. |
confirmation_required | La tool es destructiva y el cliente no puede confirmar: está en la era 2025 o no declaró formularios de elicitation. Usa un cliente en la revisión 2026-07-28 con elicitation. No se ejecutó nada. |
confirmation_replayed | La confirmación enviada ya se había usado — cada una ejecuta una llamada una vez. Llama la tool de nuevo para que se te pregunte otra vez. No se ejecutó nada. |
confirmation_unavailable | El servidor no pudo registrar la confirmación ahora, así que rechazó la tool. No se ejecutó nada; inténtalo de nuevo más tarde. |
Y los cuatro que el propio MCP agrega, porque son sobre autorización, no sobre el recurso:
code | Quién lo resuelve |
|---|---|
insufficient_scope | El alcance del token no llega a la tool: el recurso no está en el token, o falta acceso de escritura a él. Usa un token que alcance el recurso con el acceso pedido — por el flujo OAuth el acceso es solo de lectura hoy; un token personal puede traer escritura. |
insufficient_permission | Un admin de la organización, concediendo el permiso que el error nombra. |
membership_inactive | Reactivar a la persona que autorizó el cliente — ningún permiso arregla un vínculo muerto. |
key_owner_not_member | Autorizar el cliente de nuevo con una cuenta que sea miembro de la organización. |
Esos cuatro están separados a propósito: son conversaciones distintas, con personas distintas. Un error único diría "no puedes" sin decir a quién pedírselo. Ve Autenticación.
input_required no es un error
En la era 2026-07-28, el primer tools/call de una tool destructiva puede volver con resultType: "input_required" y un pedido de confirmación al usuario. Es el flujo normal, no una falla: el cliente muestra la pregunta y reenvía la misma llamada con la respuesta. Ve Confirmación de tools destructivas.
Errores de protocolo
Un mensaje malformado recibe un objeto de error JSON-RPC, no un resultado:
| Código | Significado |
|---|---|
-32700 | Parse error — el cuerpo no es JSON válido |
-32600 | Invalid request — no es un objeto JSON-RPC, o es un array (el batching no es soportado) |
-32601 | Method not found |
-32602 | Invalid params — tool, prompt o argumento inexistente, name ausente; en la era 2026-07-28, también resource no encontrado |
-32002 | Resource no encontrado — solo en la era 2025 (la 2026-07-28 usa -32602) |
-32603 | Internal error — fallo inesperado al ejecutar la tool |
{ "jsonrpc": "2.0", "id": 3,
"error": { "code": -32601, "message": "Method not found: tools/describe" } }
Errores de transporte
Los rechazos que ocurren antes de leer el mensaje JSON-RPC son respuestas HTTP comunes, con el envoltorio de error de la API: token ausente o inválido, versión de protocolo no soportada, Origin fuera de la allowlist, límite de peticiones, cuerpo de más de 1 MB (413, con el error JSON-RPC -32600 Request body too large). Están listados en Autenticación → Modos de fallo.
Por qué isError y no un error JSON-RPC
Un 404 en un usuario del portal no es un defecto del cliente MCP — es información sobre el mundo, y el modelo del otro lado la necesita para corregirse. Enterrarla en un error de protocolo haría que el cliente la tratara como fallo de transporte, escondiera el texto y, en el mejor caso, reintentara idéntico. De ahí la regla: si el llamador puede actuar, es un resultado; si la petición está rota, es un error.
Observabilidad
Cada tools/call escribe una línea estructurada con la tool, la organización, el token, el estado y la duración. Las escrituras también aparecen en la traza de auditoría de la organización, escrita por el propio endpoint despachado y atribuida a la persona que autorizó el cliente — lo que hizo un agente aparece al lado de lo que hizo una persona, en la misma pantalla.