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

# Limites e erros do MCP

> Os limites de requisições e de ferramentas do servidor MCP da Square Cloud por plano, como é um TOOL_RATE_LIMITED e o que fazer em cada erro que um cliente pode receber.

## Limites

Os limites são por conta e compartilhados por todas as conexões MCP dela. Cada camada se soma à anterior:

1. **Requisições ao servidor MCP.** Até 60 por minuto por conta, ou o [limite de requisições da API](https://docs.squarecloud.app/pt-br/api-reference/limitations-and-restrictions.md#limites-da-api) do seu plano, se for menor. Elas contam à parte das suas chamadas à API, então um agente muito ativo nunca bloqueia suas outras integrações. Acima disso, as requisições respondem `429 RATE_LIMITED` por 60 segundos.
2. **Conta bloqueada na API fica bloqueada aqui também.** Enquanto a conta estiver acima do limite de requisições da API, o servidor MCP também responde `429 RATE_LIMITED`.
3. **O orçamento de ferramentas:** chamadas de ferramentas por minuto, metade do limite de requisições da API do seu plano e no máximo 60, já que uma chamada de ferramenta faz muito mais trabalho que uma requisição.
4. **Tetos por ferramenta** para as ferramentas que leem ou escrevem dentro da sua aplicação ou consultam a rede de borda.
5. **Os limites por ferramenta do Cubic**, o assistente de IA da Square Cloud. O MCP e o Cubic os compartilham, por conta.

As camadas 3, 4 e 5 respondem com um resultado de ferramenta `TOOL_RATE_LIMITED`, descrito abaixo.

| Ferramentas | Chamadas por minuto | Pausa ao atingir |
| - | - | - |
| Todas as ferramentas, `HOBBY-1` | 15 | 60 s |
| Todas as ferramentas, `HOBBY-2` | 30 | 60 s |
| Todas as ferramentas, `STANDARD-4` e acima | 60 | 60 s |
| `list_files`, `read_file` | 20 cada | 60 s |
| `search_files` | 3 | 120 s |
| `list_env_vars` | 10 | 60 s |
| `create_file`, `edit_file`, `patch_file`, `rename_file` | 10 cada | 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 | 60 s |
| `search_help_center` | 4 | 60 s |
| `list_help_center` | 2 | 60 s |
| `start_application`, `stop_application`, `restart_application` | 10 cada | 120 s |

* **Toda chamada de ferramenta conta**, incluindo chamadas recusadas por um recurso ou por um escopo que depende dos argumentos (como `restart` em `set_env_vars`).
* **No `HOBBY-1`**, por exemplo, o MCP nunca passa de 15 chamadas de ferramentas por minuto, e a sua CLI, os seus SDKs e os seus bots mantêm todo o limite de requisições da API do plano.
* **Os commits seguem um ritmo só**, compartilhado com a API, a CLI e o dashboard: um a cada 2 segundos por conta e um a cada 5 segundos por aplicação. Antes disso, `commit_application` responde `RATE_LIMITED`.

### Zips e arquivos

* **Zip:** `upload_application` e `commit_application` aceitam um zip de até 1 MB, enviado em base64, com até 100 MB depois de descompactado. O dashboard e a [CLI](https://docs.squarecloud.app/pt-br/cli-reference/deploy.md) aceitam zips de até 100 MB: use-os para um projeto maior.
* **Arquivos:** `commit_application` aceita até 50 arquivos de texto, de até 128 KB cada e 512 KB no total. Eles não podem ser arquivos ocultos, arquivos `.env`, chaves privadas nem o arquivo de configuração, que muda por `edit_config_file`.

### TOOL\_RATE\_LIMITED

Uma ferramenta acima de um limite não roda. A resposta é um resultado de ferramenta comum marcado com `isError: true`, não um erro HTTP, então a conexão continua 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."
}
```

Quando o limite atingido é o orçamento de ferramentas, o `summary` diz `too many AI actions in a short time` e todas as ferramentas esperam; caso contrário, só aquela ferramenta espera. Se o cliente chamar a mesma ferramenta de novo enquanto ela ainda está limitada, essa segunda recusa seguida responde `TOOL_EXECUTION_FAILED`, que diz ao cliente para parar e a você para esperar alguns minutos ou usar o dashboard.

## Erros

### Erros HTTP

Estes voltam como o status HTTP da requisição, com um corpo JSON que traz `code`.

| Status | Código | Quando | O que fazer |
| - | - | - | - |
| `401` | `ACCESS_DENIED` | Nenhuma chave, ou a chave está errada, foi revogada ou expirou. A resposta traz o desafio OAuth, então Claude e ChatGPT pedem que você entre de novo. | Reconecte o cliente ou crie uma nova [chave de API](https://docs.squarecloud.app/pt-br/mcp/connect.md#criar-uma-chave-de-api). |
| `403` | `ACCESS_DENIED` | Foi enviado um token de sessão do dashboard em vez de uma chave de API. | Conecte com OAuth ou com uma chave de API. |
| `403` | `MISSING_SCOPE` | A chave não tem o escopo `mcp`. Também é retornado quando uma chave do Claude ou do ChatGPT é usada na API REST. | Crie uma chave com `mcp`. |
| `403` | `UPGRADE_REQUIRED` | A conta não tem um plano ativo. | Assine ou renove um [plano](https://docs.squarecloud.app/pt-br/platform/plans.md). |
| `421` | `WRONG_HOST` | A requisição foi para outro endereço da Square Cloud, como `api.squarecloud.app`. | Use `https://mcp.squarecloud.app/mcp`. |
| `429` | `RATE_LIMITED` | Acima do limite de requisições ao servidor MCP, ou a conta está bloqueada pelo limite de requisições da API. | Espere um minuto e reduza o ritmo do cliente. |
| `400` | Erro JSON-RPC | Uma versão de protocolo não suportada (`-32022`, com a lista das suportadas) ou uma requisição malformada. | Atualize o cliente. |

### Ao conectar

| O que você vê | Por quê | O que fazer |
| - | - | - |
| `UNKNOWN_CLIENT` ou `INVALID_REDIRECT_URI` em uma página de `mcp.squarecloud.app` | Só o Claude, com a identidade publicada dele, e o ChatGPT entram com OAuth. | No Claude, escolha **Use Claude's published identity**. Em outros clientes, conecte com uma [chave de API](https://docs.squarecloud.app/pt-br/mcp/connect.md#criar-uma-chave-de-api). |
| `The account is at its API key limit` | A conta já tem 10 chaves. | Revogue uma chave nas [configurações de segurança da sua conta](https://squarecloud.app/pt-br/account/security) e conecte de novo. |
| A página de consentimento diz que o pedido expirou | Ele dura 10 minutos. | Comece a conexão de novo pelo cliente. |

### Resultados de ferramentas

Estes voltam dentro de um resultado de ferramenta, como `code`, ao lado de um `summary` que o cliente lê.

| Código | Significado | O que fazer |
| - | - | - |
| `SNAPSHOT_NOT_READY` | O [snapshot de segurança](https://docs.squarecloud.app/pt-br/mcp/permissions-and-safety.md#exclusões-e-restaurações) tirado antes de uma exclusão, de uma restauração ou de um `commit_application` com `snapshot` ainda está sendo gerado. Nada rodou. | O cliente tenta de novo com os mesmos argumentos em cerca de 2 minutos. |
| `MISSING_SCOPE` | Esta chamada precisa de um escopo que a chave não tem, como `databases:read` para as métricas de um banco de dados. | Use uma chave com esse escopo. |
| `RESOURCE_NOT_ALLOWED` | A chave está restrita a outras aplicações e bancos de dados, ou nenhum dos que ela cobre tem esse nome. | Use uma chave que cubra o recurso. |
| `TOOL_RATE_LIMITED` | Um [limite](#limites) foi atingido. | Espere o tempo indicado no `summary`. |
| `TOOL_EXECUTION_FAILED` | A mesma ferramenta atingiu um limite duas vezes seguidas, ou falhou. | Espere alguns minutos ou use o dashboard. |
| `APP_NOT_FOUND`, `DATABASE_NOT_FOUND` | Nenhuma aplicação ou banco de dados corresponde ao nome ou ID. | Peça ao cliente que os liste antes. |
| `INVALID_ZIP` | `zip` não está em base64, ou o zip está danificado. | Gere o zip de novo e envie outra vez. |
| `ZIP_TOO_LARGE` | O zip passa de 1 MB, ou de 100 MB depois de descompactado. | Envie um zip menor, ou faça o deploy do projeto pela [CLI](https://docs.squarecloud.app/pt-br/cli-reference/deploy.md) ou pelo dashboard. |
| `MISSING_MANIFEST` | O zip do `upload_application` não tem `squarecloud.app` na raiz, muitas vezes porque o projeto está dentro de uma pasta do zip. | Compacte o conteúdo da pasta, com o `squarecloud.app` (`DISPLAY_NAME`, `MAIN`, `MEMORY`, `VERSION`) na raiz. |
| `BLOCKED_PATH` | Um caminho aponta para fora da pasta de destino, ou o zip tem arquivos dentro da pasta `.squarecloud`, que é da plataforma e não pode ser modificada. Em `files`, arquivos ocultos, arquivos `.env`, chaves privadas e o arquivo de configuração também são recusados. | Tire esses arquivos e envie de novo. |
| `INVALID_PATH` | `path` não é uma pasta em que um commit pode escrever. | Escolha outra pasta da aplicação. |
| `RESTORE_IN_PROGRESS` | Uma restauração está em andamento na aplicação. | Espere ela terminar e tente de novo. |
| `RATE_LIMITED` | Um commit chegou cedo demais depois do anterior. | Espere alguns segundos e tente de novo. |
| `COMMIT_FAILED` | Não foi possível gravar a nova versão na aplicação. | Tente de novo, ou envie pelo dashboard. |

Uma ferramenta que a sua chave não pode usar, ou que não existe, responde com o erro JSON-RPC `-32602` `Unknown tool`. Confira os [escopos](https://docs.squarecloud.app/pt-br/mcp/permissions-and-safety.md#escopos) da chave. Outros códigos vêm da própria ferramenta, e o `summary` os explica.


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