Errors

Platica's MCP server distinguishes two classes of error, aligned with the MCP spec:

Class	When it's returned	How the client sees it
Tool execution error	The tool ran but the result was a recoverable failure.	`tools/call` returns `{ result: { isError: true, content: [...] } }`. The model can read the message and retry.
Protocol error (JSON-RPC)	The request is structurally invalid or untraversable.	Standard JSON-RPC `{ error: { code, message } }` response.

Execution errors (`isError: true`)

Every non-2xx HTTP response from the REST API becomes an execution error. content[0].text contains the raw body (typically JSON with code, error, details).

Common catalog

REST status	Cause	How to fix
`400`	Invalid arguments.	Read `errors[]` in the response and fix the flagged field.
`400 Must specify a valid workspace...`	Multi-workspace API Key with `workspace` omitted.	Pass `workspace: "<id>"` in the arguments.
`401`	API Key missing, invalid, or disabled.	Regenerate the Key in the Platica dashboard. Check the `Authorization` header.
`403`	The API Key doesn't have access to the requested workspace/resource.	Use a key with the right scope.
`404`	Resource (client, agent, campaign, webhook, …) doesn't exist in that workspace.	Confirm the ID. If the key is multi-workspace, try passing `workspace`.
`422`	The resource exists but is in an incompatible state (e.g. agent without workspace).	Inspect the error details.
`500`	Backend internal error.	Retry. If it persists, check the logs or contact support.

Example

{
  "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

When the API response is JSON, the MCP server also passes it parsed in structuredContent, which makes programmatic handling easy for the model without re-parsing.

Protocol errors

These JSON-RPC codes are returned when the request can't even be executed:

Code	Meaning
`-32001`	`Unauthorized: missing or invalid Authorization header.` Header missing or not in `Bearer pl_key_...` format.
`-32000`	`GET /mcp` or `DELETE /mcp` was called. The server only accepts `POST`.
`-32602`	Invalid arguments in the JSON-RPC call (not the tool — the JSON-RPC itself is malformed).
`-32603`	Internal MCP server error (unhandled exception). Retry.

Argument validation

If a tool's arguments don't pass validation against the inputSchema, the server responds with an execution error (isError: true) that includes:

content[0].text: human-readable list of issues (path: message).
structuredContent.issues: array of { path, message, code } (Zod format).

This gives the model enough context to retry with corrected arguments in the same turn.