Errores
Los fallos llegan por dos canales distintos, y la diferencia importa: uno es una solicitud rota, el otro es algo que el modelo debe leer y sobre lo que debe reaccionar.
Errores de tool
Todo aquello sobre lo que quien llama puede actuar — validación, no encontrado, scope insuficiente, permiso insuficiente, un error del endpoint — vuelve como una respuesta JSON-RPC exitosa cuyo resultado está marcado con isError, llevando el envelope 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\": \"not_found\" } }" }]
} }
El vocabulario de code es el de la API REST, sin cambios — ver Errores de la API para la lista completa. Los códigos que más encontrarás:
code | Cuándo |
|---|---|
validation_failed | Los argumentos no pasaron la validación del schema; details nombra los campos |
not_found | No existe el registro, o pertenece a otro workspace |
conflict | external_id en uso, o idempotency_key repetida con un body distinto |
unprocessable_entity | Violación de regla de negocio, p.ej. reprocesar un correo en un estado que no lo permite |
insufficient_scope | El token del cliente conectado no alcanza la tool: el recurso no está en el token, o falta el acceso de escritura a él. Por el flujo OAuth, el acceso hoy es de solo lectura; un token personal puede llevar escritura |
insufficient_permission | La persona no tiene el permiso que la tool exige en esta organización |
method_not_allowed | La operación de la tool no está soportada en esa ruta |
user_declined | En el protocolo 2026-07-28, el usuario rechazó o canceló la confirmación de una tool destructiva. Nada cambió |
confirmation_required | Una tool destructiva llamada por un cliente que no puede confirmarla — era 2025, o 2026-07-28 sin formularios de elicitation. No se ejecutó nada |
confirmation_replayed | Se envió de nuevo una confirmación ya usada. No se ejecutó nada; llama a la tool sin requestState para volver a preguntar |
confirmation_unavailable | El servidor no pudo registrar la confirmación en ese momento. No se ejecutó nada; inténtalo de nuevo más tarde |
insufficient_scope e insufficient_permission están separados porque quien los resuelve es distinto: el primero, quien sea dueño del cliente conectado y de su token; el segundo, el administrador de la organización, en el dashboard.
input_required no es un error
En el protocolo 2026-07-28, el primer tools/call de una tool destructiva puede volver con resultType: "input_required" y una solicitud de confirmación para el usuario. Es el flujo normal, no un fallo: el cliente muestra la pregunta y envía la misma llamada de nuevo con la respuesta. Ver Confirmación de tools destructivas.
Errores de protocolo
Un mensaje malformado recibe un objeto de error JSON-RPC en vez de un resultado:
| Código | Significado |
|---|---|
-32700 | Parse error — el body no es JSON válido |
-32600 | Solicitud inválida — no es un objeto JSON-RPC, o es un batch en array (no soportado) |
-32601 | Método no encontrado |
-32602 | Params inválidos — tool, prompt o argumento desconocido, o falta name; en 2026-07-28, también un resource no encontrado |
-32002 | Resource no encontrado — solo en las revisiones de 2025 (2026-07-28 usa -32602) |
-32020 | Discrepancia de headers — en 2026-07-28, un header MCP-Protocol-Version, Mcp-Method o Mcp-Name que no coincide con el body (HTTP 400) |
-32022 | Versión de protocolo no soportada — data.supported lista las soportadas (HTTP 400) |
-32603 | Error interno — fallo inesperado al ejecutar la tool |
Un body de solicitud de más de 1 MB (1.048.576 bytes) se rechaza con HTTP 413 y -32600 antes de ejecutar nada — y, cuando el Content-Length lo declara, antes de la autenticación:
{ "jsonrpc": "2.0", "id": null, "error": { "code": -32600, "message": "Request body too large (limit 1048576 bytes)" } }
{ "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 normales con el envelope de error de la API — token ausente, token inválido o emitido para otro recurso, origen no permitido, workspace no elegido, persona que no es miembro, límite de solicitudes, authorization server no disponible (503). Están listados en Autenticación.
Correlación
Cada respuesta lleva un header X-Request-Id. Inclúyelo al reportar un problema para poder recuperar el trace. Cada llamada a una tool también se escribe en el registro de auditoría con el nombre de la tool, el workspace, el jti del token, si el token vino del flujo OAuth o es un token personal, la persona, el estado resultante y la duración — nunca la dirección, el asunto ni el cuerpo de un correo.