Errores

El servidor informa de una llamada fallida como un resultado, no como un error JSON-RPC. El resultado lleva isError: true y el problema RFC 9457 de la API REST como JSON en content[0].text. No lleva structuredContent: la especificación exige que structuredContent coincida con el outputSchema de la herramienta, y un error no lo cumple.

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

El problema incluye type, title, status, code, detail, requestId y, cuando corresponden, errors[], requiredScope, requiredAddon y retryAfter. Una llamada con clave de idempotencia también devuelve meta.idempotencyKey dentro del problema. Cita requestId cuando pidas ayuda. Es el mismo documento de problema que devuelve la API REST: consulta Errores.

Una petición mal formada, un método desconocido o una herramienta desconocida es un error JSON-RPC con un código como -32600, -32601, -32602 o -32700, y su mensaje está en inglés. Una llamada sin credencial no es JSON-RPC: es un HTTP 401 con un cuerpo de problema. Consulta la referencia del protocolo.

Client.callTool del SDK de TypeScript y call_tool del SDK de Python devuelven el resultado; ninguno lanza una excepción por un error de herramienta. Comprueba isError y analiza el primer bloque de texto. Solo los fallos de protocolo, como una herramienta desconocida o un timeout, lanzan excepción.

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

En los paquetes 2.x el campo es is_error en Python y el transporte se construye de otra forma; el contrato del servidor es el mismo. Consulta Construir tu propio cliente.

Una herramienta que necesita un permiso (scope) que la conexión no tiene devuelve insufficient_scope con requiredScope. El servidor no responde con un 403 que pida al cliente ampliar sus permisos, así que ningún cliente añade el permiso por sí solo. Para añadir uno, elimina el conector y vuelve a añadirlo, y marca el permiso en la pantalla de consentimiento. Con una clave, crea otra clave con el permiso.

Se aplica la tabla de decisión de la API REST. Un resultado te indica que es una repetición con meta.idempotentReplay: true.

Cada código de error tiene su propia página en la pestaña de la API REST, con cuándo ocurre y qué hacer.