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 `structuredContent.details` or `issues` and fix the flagged fields.
`400 Must specify a valid workspace...`	The credential covers several workspaces and `workspace` was omitted.	Call `list_workspaces` and pass `workspace: "<id>"`.
`401`	Credential missing, invalid, revoked, or expired.	With OAuth, let the client refresh or re-authorize. With an API Key, regenerate the key and check the `Authorization` header.
`402`	The workspace reached its credit limit.	Check the plan or usage before repeating the tool.
`403` + `insufficient_scope`	The access token doesn't have `platica:write` and the tool writes.	The client must re-authorize requesting that scope. The `WWW-Authenticate` header says so.
`403` + `Missing … permission`	Your role in the workspace doesn't cover that module.	Sign in with an account that does, or use an API Key.
`403`	The credential doesn't have access to the workspace or resource.	Confirm the workspace and permissions.
`404`	Resource (client, agent, campaign, webhook, …) doesn't exist in that workspace.	Confirm the ID. If the credential is multi-workspace, try passing `workspace`.
`409`	The resource is busy or has an identity/state conflict.	Fetch it again; retry busy conversations with backoff.
`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.
`502` / `504`	Internal service failure or timeout.	Fetch the chat or conversation before retrying; the operation may have completed.
`503`	Service temporarily unavailable.	Retry with backoff.

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.` The Bearer is missing, or it isn't a valid `pl_at_…` / `pl_key_…`. On this `401`, the `WWW-Authenticate` header points at OAuth discovery so the client can start the flow.
`-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.

A 401 without an Authorization header is not a misconfiguration: it's the start of OAuth. The client should read WWW-Authenticate and follow discovery. If you paste an expired token by hand, the same code stops the request before any tool runs.

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

In send_chat_message, delay and scheduleAt are mutually exclusive. Sending both produces a 400 validation error; fix the arguments before retrying the tool.

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