Errors

The server reports a failed call as a result, not as a JSON-RPC error. The result has isError: true and the RFC 9457 problem of the REST API as JSON in content[0].text. It has no structuredContent: the specification requires structuredContent to match the tool's outputSchema, and an error does not.

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "{\"type\":\"https://docs.filmo.io/errors/rate_limited\",\"title\":\"Rate limit exceeded\",\"status\":429,\"code\":\"rate_limited\",\"detail\":\"Rate limit exceeded: retry in 17 seconds\",\"requestId\":\"req_…\",\"retryAfter\":17,\"meta\":{\"rateLimit\":{\"limit\":120,\"remaining\":0,\"reset\":17}}}"
    }
  ]
}

The problem carries type, title, status, code, detail, requestId and, when they apply, errors[], requiredScope, requiredAddon and retryAfter. A call with an idempotency key also returns meta.idempotencyKey inside the problem. Quote requestId when you ask for help. It is the same problem document the REST API returns: see Errors.

A malformed request, an unknown method or an unknown tool is a JSON-RPC error with a code such as -32600, -32601, -32602 or -32700, and its message is in English. A call without a credential is not JSON-RPC: it is an HTTP 401 with a problem body. See the protocol reference.

Client.callTool of the TypeScript SDK and call_tool of the Python SDK return the result; neither raises for a tool error. Check isError and parse the first text block. Only protocol failures, such as an unknown tool or a timeout, raise.

const result = await client.callTool({ name, arguments: args });
if (result.isError) {
  const text = (result.content as { type: string; text?: string }[]).find((c) => c.type === "text")?.text ?? "{}";
  const problem = JSON.parse(text); // { code, status, detail, requestId, retryAfter?, requiredScope? }
  if (problem.code === "rate_limited") await sleep(problem.retryAfter * 1000);
}

import asyncio, json

async def call(session, name, args):
    result = await session.call_tool(name, arguments=args)
    if result.isError:
        problem = json.loads(result.content[0].text)  # code, status, detail, requestId, retryAfter?, requiredScope?
        if problem["code"] == "rate_limited":
            await asyncio.sleep(problem["retryAfter"])
    return result

In the 2.x packages the field is is_error in Python and the transport is built differently; the contract of the server is the same. See Build your own client.

A tool that needs a scope the connection does not have returns insufficient_scope with requiredScope. The server does not answer with a 403 that asks the client to widen its scopes, so no client adds the scope by itself. To add one, remove the connector and add it again, and check the scope in the consent screen. With a key, create another key with the scope.

The decision table of the REST API applies. A result tells you it is a repetition with meta.idempotentReplay: true.

Every error code has its own page in the REST API tab, with when it happens and what to do.