Límites y errores
Una solicitud MCP puede fallar en la conexión, el protocolo o la herramienta. Revisa el mensaje devuelto y los detalles estructurados antes de reintentar; algunos fallos requieren corregir la entrada o cambiar los permisos.
Límites
| Límite | Comportamiento |
|---|---|
| Llamadas a herramientas | Hasta 600 solicitudes tools/call por minuto por clave. |
| Generación de PDF | Hasta 60 llamadas generate_document por minuto por clave, que también cuentan en el límite general. |
| Listas paginadas | 50 resultados por defecto y un máximo de 100 por página. Sigue el next_cursor devuelto. |
| Plantillas entre proyectos | Listar sin project_id se limita a 500 plantillas. Si truncated es true, lista proyectos individuales con paginación. |
| Importación de imágenes | Imágenes públicas PNG, JPEG o WebP de hasta 10 MB; también se aplican los límites de almacenamiento de recursos del espacio de trabajo. |
| Enlaces de vista previa | Válidos unos 15 minutos. Vuelve a leer el borrador para obtener un enlace nuevo. |
| Enlaces de descarga de PDF | URL firmadas de corta duración. Vuelve a leer el documento para obtener un enlace nuevo. |
generate_document consume un crédito de generación cuando crea un documento nuevo. Obtener un documento existente con la misma clave de idempotencia no consume otro crédito. Los límites de solicitudes siguen aplicándose a las llamadas a herramientas.
Autenticación y permisos
HTTP 401 indica que la clave bearer falta, no es válida, ha caducado o se ha revocado. Comprueba el encabezado Authorization, sustituye una clave de API no válida o inicia sesión de nuevo mediante OAuth. La respuesta incluye un desafío WWW-Authenticate: Bearer con información de descubrimiento de OAuth.
Herramientas ausentes o llamadas sin permiso suelen indicar que la conexión carece del permiso requerido. Compara tus permisos con la tabla de permisos y herramientas, vuelve a conectar con los permisos necesarios y actualiza la lista de herramientas del cliente.
Recurso no encontrado puede indicar que el ID es incorrecto o que el recurso queda fuera del espacio de trabajo o del acceso a recursos de tu conexión. Comprueba ambos antes de reintentar.
HTTP 405 al visitar desde el navegador es lo esperado para un GET simple al endpoint MCP. Conéctate con un cliente MCP Streamable HTTP.
Errores de herramientas
Un fallo de herramienta se devuelve como resultado MCP con isError: true. Incluye texto legible y, cuando está disponible, structuredContent con un código y detalles. Una solicitud HTTP correcta por sí sola no significa que la herramienta haya tenido éxito.
| Error o condición | Qué hacer |
|---|---|
rate_limited | Espera retry_after_seconds y reintenta. Reduce la frecuencia de consulta. |
invalid_document | Corrige las rutas de campo y los mensajes indicados con ayuda de describe_schema. |
invalid_operation | Corrige la operación indicada. No se guardó ninguna operación de esa llamada de edición. |
lock_version_conflict | Revisa el borrador actual devuelto, vuelve a aplicar los cambios y usa su último lock_version. |
| Plantilla no publicada | Publica un borrador válido antes de generar o elige una plantilla publicada. |
| Borrador con problemas de publicación | Resuelve problems, revisa el borrador de nuevo y después publica. |
idempotency_key_in_flight | Espera brevemente y reintenta la misma generación con la misma clave. |
credits_exhausted, no_active_period, period_ended, subscription_not_entitled | Resuelve los créditos o el acceso de suscripción del espacio de trabajo. Estos errores incluyen retryable: false. |
storage_limit_exceeded | Resuelve el límite de almacenamiento de recursos del espacio de trabajo antes de importar de nuevo. |
| Error de descarga o formato de imagen | Usa una URL de imagen pública accesible con un formato y tamaño admitidos. |
Un borrador con publishable: null no ha pasado la comprobación de publicación. Reintenta la comprobación más tarde en lugar de interpretar una lista problems vacía como confirmación de que está listo.
Fallos de generación
Un documento en cola puede fallar después. get_document devuelve status: "failed" con un failure que contiene un código y un mensaje. Explica el fallo y corrige su causa antes de iniciar otra generación.
Si el documento está completed pero pdf_url no está disponible, reintenta get_document; puede ocurrir por un problema temporal de almacenamiento. No inicies otra generación solo para obtener un enlace de descarga.
Errores de protocolo
El JSON mal formado, los métodos JSON-RPC desconocidos, los parámetros no válidos y los recursos que no pueden leerse usan respuestas de error JSON-RPC. Corrige la estructura de la solicitud o la URI del recurso. Normalmente los clientes MCP gestionan la inicialización y la negociación del protocolo.
Para fallos de herramientas, sigue los indicadores estructurados retryable y retry_after_seconds cuando aparezcan. En los reintentos de generación, conserva la misma clave de idempotencia no vacía para el mismo documento previsto; las llamadas de creación y edición de plantillas no tienen esta garantía de reintento.
Vuelve a Autenticación, Generar un PDF o Crear una plantilla.