> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Límites y errores del MCP

> Los límites de solicitudes y de herramientas del servidor MCP de Square Cloud por plan, cómo se ve TOOL_RATE_LIMITED y qué hacer ante cada error que puede recibir un cliente.

## Límites

Los límites son por cuenta y los comparten todas sus conexiones MCP. Cada capa se aplica sobre la anterior:

1. **Solicitudes al servidor MCP.** Hasta 60 por minuto por cuenta, o el [límite de tasa de la API](https://docs.squarecloud.app/es/api-reference/limitations-and-restrictions.md#límites-de-la-api) de tu plan si es menor. Cuentan aparte de tus llamadas a la API, así que un agente muy activo nunca bloquea tus otras integraciones. Al superarlo, las solicitudes responden `429 RATE_LIMITED` durante 60 segundos.
2. **Una cuenta bloqueada en la API también queda bloqueada aquí.** Mientras la cuenta supere su límite de tasa de la API, el servidor MCP también responde `429 RATE_LIMITED`.
3. **El presupuesto de herramientas:** llamadas a herramientas por minuto, la mitad de la tasa de API de tu plan y como máximo 60, ya que una llamada a una herramienta hace mucho más trabajo que una solicitud.
4. **Límites por herramienta** para las herramientas que leen o escriben dentro de tu aplicación o consultan la red del edge.
5. **Los límites por herramienta de Cubic**, el asistente de IA de Square Cloud. El MCP y Cubic los comparten, por cuenta.

Las capas 3, 4 y 5 responden con un resultado de herramienta `TOOL_RATE_LIMITED`, descrito más abajo.

| Herramientas | Llamadas por minuto | Pausa al alcanzarlo |
| - | - | - |
| Todas las herramientas, `HOBBY-1` | 15 | 60 s |
| Todas las herramientas, `HOBBY-2` | 30 | 60 s |
| Todas las herramientas, `STANDARD-4` y superiores | 60 | 60 s |
| `list_files`, `read_file` | 20 cada una | 60 s |
| `search_files` | 3 | 120 s |
| `list_env_vars` | 10 | 60 s |
| `create_file`, `edit_file`, `patch_file`, `rename_file` | 10 cada una | 120 s |
| `edit_config_file` | 5 | 120 s |
| `commit_application` | 5 | 120 s |
| `delete_file` | 5 | 180 s |
| `get_application_logs` | 10 | 60 s |
| `get_application_status` | 20 | 60 s |
| `get_metrics_history` | 10 | 60 s |
| `get_network_analytics`, `get_network_errors`, `get_network_performance`, `get_network_logs` | 5 cada una | 60 s |
| `search_help_center` | 4 | 60 s |
| `list_help_center` | 2 | 60 s |
| `start_application`, `stop_application`, `restart_application` | 10 cada una | 120 s |

* **Cada llamada a una herramienta cuenta**, incluidas las llamadas rechazadas por un recurso o por un scope que depende de los argumentos (como `restart` en `set_env_vars`).
* **En `HOBBY-1`**, por ejemplo, el MCP nunca pasa de 15 llamadas a herramientas por minuto, y tu CLI, tus SDKs y tus bots conservan toda la tasa de API del plan.
* **Los commits comparten un mismo ritmo** con la API, la CLI y el dashboard: uno cada 2 segundos por cuenta y uno cada 5 segundos por aplicación. Antes de eso, `commit_application` responde `RATE_LIMITED`.

### Zips y archivos

* **Zip:** `upload_application` y `commit_application` aceptan un zip de hasta 1 MB, enviado en base64, y de hasta 100 MB una vez descomprimido. El dashboard y la [CLI](https://docs.squarecloud.app/es/cli-reference/deploy.md) aceptan zips de hasta 100 MB: úsalos para un proyecto más grande.
* **Archivos:** `commit_application` acepta hasta 50 archivos de texto, de hasta 128 KB cada uno y 512 KB en total. No pueden ser archivos ocultos, archivos `.env`, claves privadas ni el archivo de configuración, que se cambia con `edit_config_file`.

### TOOL\_RATE\_LIMITED

Una herramienta que supera un límite no se ejecuta. La respuesta es un resultado de herramienta normal marcado con `isError: true`, no un error HTTP, así que la conexión sigue funcionando:

```json theme={"system"}
{
  "ok": false,
  "code": "TOOL_RATE_LIMITED",
  "summary": "read_file did NOT run: this action is on a short safety cooldown. Continue with what you already have, and tell the user it can run again in about 60 seconds."
}
```

Cuando el límite alcanzado es el presupuesto de herramientas, el resumen dice `too many AI actions in a short time` y todas las herramientas esperan; si no, solo espera esa herramienta. Si el cliente vuelve a llamar a la misma herramienta mientras sigue limitada, ese segundo rechazo seguido responde `TOOL_EXECUTION_FAILED`, que le indica al cliente que se detenga y a ti que esperes unos minutos o uses el dashboard.

## Errores

### Errores HTTP

Llegan como el estado HTTP de la solicitud, con un cuerpo JSON que incluye `code`.

| Estado | Código | Cuándo | Qué hacer |
| - | - | - | - |
| `401` | `ACCESS_DENIED` | No hay clave, o la clave es incorrecta, fue revocada o expiró. La respuesta incluye el desafío OAuth, así que Claude y ChatGPT te piden iniciar sesión de nuevo. | Vuelve a conectar el cliente o crea una nueva [clave de API](https://docs.squarecloud.app/es/mcp/connect.md#crear-una-clave-de-api). |
| `403` | `ACCESS_DENIED` | Se envió un token de sesión del dashboard en lugar de una clave de API. | Conéctate con OAuth o con una clave de API. |
| `403` | `MISSING_SCOPE` | La clave no tiene el scope `mcp`. También se devuelve cuando una clave de Claude o ChatGPT se usa en la REST API. | Crea una clave con `mcp`. |
| `403` | `UPGRADE_REQUIRED` | La cuenta no tiene un plan activo. | Suscríbete a un [plan](https://docs.squarecloud.app/es/platform/plans.md) o renuévalo. |
| `421` | `WRONG_HOST` | La solicitud fue a otra dirección de Square Cloud, como `api.squarecloud.app`. | Usa `https://mcp.squarecloud.app/mcp`. |
| `429` | `RATE_LIMITED` | Se superó el límite de solicitudes al servidor MCP, o la cuenta está bloqueada por su límite de tasa de la API. | Espera un minuto y reduce el ritmo del cliente. |
| `400` | Error JSON-RPC | Una versión del protocolo no admitida (`-32022`, con la lista de versiones admitidas) o una solicitud mal formada. | Actualiza el cliente. |

### Al conectar

| Lo que ves | Por qué | Qué hacer |
| - | - | - |
| `UNKNOWN_CLIENT` o `INVALID_REDIRECT_URI` en una página de `mcp.squarecloud.app` | Solo Claude, con su identidad publicada, y ChatGPT inician sesión con OAuth. | En Claude, elige **Use Claude's published identity**. En otros clientes, conéctate con una [clave de API](https://docs.squarecloud.app/es/mcp/connect.md#crear-una-clave-de-api). |
| `The account is at its API key limit` | La cuenta ya tiene 10 claves. | Revoca una clave en la [configuración de seguridad de tu cuenta](https://squarecloud.app/es/account/security) y vuelve a conectarte. |
| La página de consentimiento dice que la solicitud expiró | Dura 10 minutos. | Inicia la conexión de nuevo desde el cliente. |

### Resultados de herramientas

Llegan dentro de un resultado de herramienta, como `code`, junto a un `summary` que lee el cliente.

| Código | Significado | Qué hacer |
| - | - | - |
| `SNAPSHOT_NOT_READY` | El [snapshot de seguridad](https://docs.squarecloud.app/es/mcp/permissions-and-safety.md#eliminaciones-y-restauraciones) que se toma antes de una eliminación, una restauración o un `commit_application` con `snapshot` todavía se está generando. No se ejecutó nada. | El cliente lo intenta de nuevo con los mismos argumentos en unos 2 minutos. |
| `MISSING_SCOPE` | Esta llamada necesita un scope que la clave no tiene, como `databases:read` para las métricas de una base de datos. | Usa una clave con ese scope. |
| `RESOURCE_NOT_ALLOWED` | La clave está restringida a otras aplicaciones y bases de datos, o ninguna de las que cubre tiene ese nombre. | Usa una clave que cubra el recurso. |
| `TOOL_RATE_LIMITED` | Se alcanzó un [límite](#límites). | Espera el tiempo que indica el resumen. |
| `TOOL_EXECUTION_FAILED` | La misma herramienta alcanzó un límite dos veces seguidas, o falló. | Espera unos minutos o usa el dashboard. |
| `APP_NOT_FOUND`, `DATABASE_NOT_FOUND` | Ninguna aplicación o base de datos coincide con el nombre o el ID. | Pide al cliente que las liste primero. |
| `INVALID_ZIP` | `zip` no está en base64, o el zip está dañado. | Genera el zip de nuevo y vuelve a enviarlo. |
| `ZIP_TOO_LARGE` | El zip supera 1 MB, o 100 MB una vez descomprimido. | Envía un zip más pequeño, o haz el deploy del proyecto con la [CLI](https://docs.squarecloud.app/es/cli-reference/deploy.md) o el dashboard. |
| `MISSING_MANIFEST` | El zip de `upload_application` no tiene `squarecloud.app` en la raíz, a menudo porque el proyecto está dentro de una carpeta del zip. | Comprime el contenido de la carpeta, con `squarecloud.app` (`DISPLAY_NAME`, `MAIN`, `MEMORY`, `VERSION`) en la raíz. |
| `BLOCKED_PATH` | Una ruta apunta fuera de la carpeta de destino, o el zip tiene archivos dentro de la carpeta `.squarecloud`, que pertenece a la plataforma y no se puede modificar. En `files` también se rechazan los archivos ocultos, los archivos `.env`, las claves privadas y el archivo de configuración. | Quita esos archivos y vuelve a enviarlo. |
| `INVALID_PATH` | `path` no es una carpeta en la que un commit pueda escribir. | Elige otra carpeta de la aplicación. |
| `RESTORE_IN_PROGRESS` | Hay una restauración en curso en la aplicación. | Espera a que termine e inténtalo de nuevo. |
| `RATE_LIMITED` | Un commit llegó demasiado pronto después del anterior. | Espera unos segundos e inténtalo de nuevo. |
| `COMMIT_FAILED` | No se pudo escribir la nueva versión en la aplicación. | Inténtalo de nuevo, o envíala desde el dashboard. |

Una herramienta que tu clave no puede usar, o una que no existe, responde el error JSON-RPC `-32602` `Unknown tool`. Revisa los [scopes](https://docs.squarecloud.app/es/mcp/permissions-and-safety.md#scopes) de la clave. Los demás códigos vienen de la propia herramienta, y el `summary` los explica.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.