Errores
Las fallas llegan por dos canales distintos, y la diferencia importa: uno es una solicitud 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 como texto:
{ "jsonrpc": "2.0", "id": 2, "result": {
"isError": true,
"content": [{ "type": "text",
"text": "{ \"error\": { \"code\": \"NOT_FOUND\", \"message\": \"...\" } }" }]
} }
Cuando el error viene del endpoint, el texto es el cuerpo original de la API — { "error": { "code", "message", "details"? } } —, con el vocabulario de code de la API REST sin cambios. Los que más vas a encontrar:
code | Cuándo |
|---|---|
VALIDATION_ERROR | Los argumentos fallaron la validación — de la propia tool (un argumento desconocido en una lectura, que el error nombra) o del endpoint; details nombra los campos. |
NOT_FOUND | No existe ese registro, o pertenece a otra organización. |
CONFLICT | El estado actual impide la operación, o hay un dato duplicado. |
Transición inválida (409) | La operación no vale en el estado del registro — por ejemplo, CHARGE_NOT_SETTLED al pedir la carta de finiquito de un cobro que no está pagado. |
INSUFFICIENT_SCOPE / FORBIDDEN | Rechazo de /v1 al recibir la llamada despachada — la verificación de alcance se repite ahí. |
USER_DECLINED | En la era 2026-07-28, el usuario rechazó o canceló la confirmación de una tool destructiva. No cambió nada. |
confirmation_required | La tool es destructiva y el cliente no puede confirmar: está en la era 2025 o no declaró elicitation de formulario. No se ejecutó nada. |
confirmation_replayed | La confirmación enviada ya se había usado — cada una ejecuta una llamada una vez. Llama a 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. Autoriza de nuevo, o usa un token 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 dueña del token — ningún permiso arregla un vínculo muerto. |
key_owner_not_member | La persona entra en el panel de Régua de Cobrança con su cuenta Kobana, o pide una invitación a 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; 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 — falla inesperada 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: token ausente o inválido (401), organización desconocida u Origin no permitido (403), host equivocado (404), cuerpo de más de 2 MB (413), límite de solicitudes (429), authorization server inalcanzable (503), versión de protocolo no soportada o cabeceras que no coinciden con el cuerpo (400). Están listados en Autenticación → Modos de falla.
Por qué isError y no un error JSON-RPC
Un 404 en un cobro 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 falla 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 solicitud está rota, es un error.
Observabilidad
Cada tools/call escribe una línea de log estructurado con la tool, la organización, el jti del token, el tipo de token (oauth o personal), el vínculo, el status y la duración. Las escrituras también aparecen en la trazabilidad de auditoría de la organización, grabada por el propio endpoint despachado y atribuida al token (api-token:<jti>).