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 `structuredContent.details` o `issues` y corrige los campos señalados.
`400 Must specify a valid workspace...`	La credencial cubre varios workspaces y se omitió `workspace`.	Llama `list_workspaces` y pasa `workspace: "<id>"`.
`401`	Credencial faltante, inválida, revocada o caducada.	Con OAuth, deja que el cliente refresque o vuelve a autorizar. Con API Key, regenera la key y revisa el header `Authorization`.
`402`	El workspace alcanzó su límite de créditos.	Revisa el plan o el consumo antes de repetir la tool.
`403` + `insufficient_scope`	El access token no tiene `platica:write` y la tool escribe.	El cliente debe reautorizar pidiendo ese scope. El header `WWW-Authenticate` lo indica.
`403` + `Missing … permission`	Tu rol en el workspace no cubre ese módulo.	Entra con una cuenta que sí lo tenga, o usa una API Key.
`403`	La credencial no tiene acceso al workspace o recurso.	Confirma el workspace y los permisos.
`404`	Recurso (cliente, agente, campaña, webhook, …) no existe en ese workspace.	Confirma el ID. Si la credencial es multi-ws, prueba pasando `workspace`.
`409`	El recurso está ocupado o hay un conflicto de identidad/estado.	Relee el recurso; si la conversación está procesando, reintenta con backoff.
`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.
`502` / `504`	Fallo o timeout de un servicio interno.	Relee el chat o conversación antes de reintentar: la operación puede haber terminado.
`503`	Servicio temporalmente no disponible.	Reintenta con backoff.

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 el Bearer, o no es un `pl_at_…` / `pl_key_…` válido. En este `401` el header `WWW-Authenticate` apunta al discovery OAuth para que el cliente arranque el flujo.
`-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.

Un 401 sin header Authorization no es un fallo de configuración: es el arranque de OAuth. El cliente debe leer WWW-Authenticate y seguir el discovery. Si tú pegas a mano un token caducado, el mismo código corta el request antes de ejecutar cualquier tool.

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).

En send_chat_message, delay y scheduleAt son mutuamente exclusivos. Enviar ambos produce un error de validación 400; corrige los argumentos antes de repetir la tool.

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