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...`	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`.
`402`	El workspace alcanzó su límite de créditos.	Revisa el plan o el consumo antes de repetir la tool.
`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`.
`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 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).

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.