Errores

El servidor MCP de Platica distingue dos clases de error, alineadas con el spec de MCP:

Clase	Cuándo se devuelve	Cómo se ve para el cliente
Error de ejecución de tool	La tool corrió pero el resultado fue un fallo recuperable.	`tools/call` retorna `{ result: { isError: true, content: [...] } }`. El modelo puede leer el mensaje y reintentar.
Error de protocolo (JSON-RPC)	El request es estructuralmente inválido o intransitable.	Respuesta `{ error: { code, message } }` estándar JSON-RPC.

Errores de ejecución (`isError: true`)

Toda respuesta HTTP no-2xx del API REST se convierte en un error de ejecución. El content[0].text contiene el body crudo (normalmente JSON con code, error, details).

Catálogo común

Status REST	Causa	Cómo corregir
`400`	Argumentos inválidos.	Lee `errors[]` en la respuesta y corrige el campo señalado.
`400 Must specify a valid workspace...`	API Key multi-workspace y se omitió `workspace`.	Pasa `workspace: "<id>"` en los argumentos.
`401`	API Key faltante, inválida o desactivada.	Regenera la Key en el dashboard de Platica. Revisa el header `Authorization`.
`403`	La API Key no tiene acceso al workspace/recurso solicitado.	Usa una key con scope correcto.
`404`	Recurso (cliente, agente, campaña, webhook, …) no existe en ese workspace.	Confirma el ID. Si la key es multi-ws, prueba pasando `workspace`.
`422`	El recurso existe pero está en un estado incompatible (ej. agente sin workspace).	Inspecciona el detalle del error.
`500`	Error interno del backend.	Reintenta. Si persiste, consulta los logs o contacta a soporte.

Ejemplo

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "{\"code\":404,\"error\":\"Client not found\",\"details\":\"...\"}"
      }
    ],
    "structuredContent": {
      "code": 404,
      "error": "Client not found"
    }
  }
}

Consejo

Cuando la respuesta del API es JSON, el servidor MCP también la pasa parseada en structuredContent, lo que facilita al modelo el manejo programático sin re-parsear.

Errores de protocolo

Estos códigos JSON-RPC se devuelven cuando la solicitud no puede siquiera ejecutarse:

Code	Significado
`-32001`	`Unauthorized: missing or invalid Authorization header.` Falta header o no tiene formato `Bearer pl_key_...`.
`-32000`	Se llamó `GET /mcp` o `DELETE /mcp`. El servidor sólo acepta `POST`.
`-32602`	Argumentos inválidos en la llamada JSON-RPC (no del tool — el JSON-RPC mismo está mal formado).
`-32603`	Error interno del servidor MCP (excepción no manejada). Reintenta.

Validación de argumentos

Si los arguments de un tool no pasan validación contra el inputSchema, el servidor responde con un error de ejecución (isError: true) que incluye:

content[0].text: lista legible de issues (path: mensaje).
structuredContent.issues: array de { path, message, code } (formato Zod).

Esto le da al modelo suficiente contexto para reintentar con argumentos corregidos en el mismo turno.