> ## 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 et erreurs du MCP

> Les limites de requêtes et d'outils du serveur MCP de Square Cloud par plan, l'aspect de TOOL_RATE_LIMITED et que faire face à chaque erreur qu'un client peut recevoir.

## Limites

Les limites s'appliquent par compte et sont partagées par toutes ses connexions MCP. Chaque niveau s'ajoute au précédent :

1. **Les requêtes vers le serveur MCP.** Jusqu'à 60 par minute et par compte, ou la [limite de débit de l'API](https://docs.squarecloud.app/fr/api-reference/limitations-and-restrictions.md#limites-de-lapi) de votre plan si elle est plus basse. Elles sont comptées à part de vos appels d'API, donc un agent très actif ne bloque jamais vos autres intégrations. Au-delà, les requêtes répondent `429 RATE_LIMITED` pendant 60 secondes.
2. **Un compte bloqué sur l'API l'est aussi ici.** Tant que le compte dépasse sa limite de débit de l'API, le serveur MCP répond aussi `429 RATE_LIMITED`.
3. **Le budget d'outils :** des appels d'outils par minute, la moitié du débit d'API de votre plan et 60 au maximum, car un appel d'outil fait beaucoup plus de travail qu'une requête.
4. **Des plafonds par outil** pour les outils qui lisent ou écrivent dans votre application ou interrogent le réseau edge.
5. **Les limites par outil de Cubic**, l'assistant IA de Square Cloud. Le MCP et Cubic les partagent, par compte.

Les niveaux 3, 4 et 5 répondent avec un résultat d'outil `TOOL_RATE_LIMITED`, décrit ci-dessous.

| Outils | Appels par minute | Pause une fois atteint |
| - | - | - |
| Tous les outils, `HOBBY-1` | 15 | 60 s |
| Tous les outils, `HOBBY-2` | 30 | 60 s |
| Tous les outils, `STANDARD-4` et supérieurs | 60 | 60 s |
| `list_files`, `read_file` | 20 chacun | 60 s |
| `search_files` | 3 | 120 s |
| `list_env_vars` | 10 | 60 s |
| `create_file`, `edit_file`, `patch_file`, `rename_file` | 10 chacun | 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 chacun | 60 s |
| `search_help_center` | 4 | 60 s |
| `list_help_center` | 2 | 60 s |
| `start_application`, `stop_application`, `restart_application` | 10 chacun | 120 s |

* **Chaque appel d'outil compte**, y compris les appels refusés pour une ressource ou pour un scope qui dépend des arguments (comme `restart` sur `set_env_vars`).
* **Sur `HOBBY-1`**, par exemple, le MCP ne dépasse jamais 15 appels d'outils par minute, et votre CLI, vos SDK et vos bots gardent tout le débit d'API du plan.
* **Les commits partagent un même rythme** avec l'API, la CLI et le tableau de bord : un toutes les 2 secondes par compte et un toutes les 5 secondes par application. Plus tôt, `commit_application` répond `RATE_LIMITED`.

### Zips et fichiers

* **Zip :** `upload_application` et `commit_application` acceptent un zip de 1 Mo au maximum, envoyé en base64, et de 100 Mo au maximum une fois décompressé. Le tableau de bord et la [CLI](https://docs.squarecloud.app/fr/cli-reference/deploy.md) acceptent des zips jusqu'à 100 Mo : utilisez-les pour un projet plus gros.
* **Fichiers :** `commit_application` accepte jusqu'à 50 fichiers texte, de 128 Ko chacun au maximum et 512 Ko au total. Il ne peut s'agir ni de fichiers cachés, ni de fichiers `.env`, ni de clés privées, ni du fichier de configuration, qui se modifie avec `edit_config_file`.

### TOOL\_RATE\_LIMITED

Un outil qui dépasse une limite ne s'exécute pas. La réponse est un résultat d'outil ordinaire marqué `isError: true`, pas une erreur HTTP, donc la connexion continue de fonctionner :

```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."
}
```

Lorsque la limite atteinte est le budget d'outils, le résumé indique `too many AI actions in a short time` et tous les outils attendent ; sinon, seul cet outil attend. Si le client appelle à nouveau le même outil alors qu'il est encore limité, ce second refus consécutif répond `TOOL_EXECUTION_FAILED` à la place, ce qui indique au client de s'arrêter et à vous d'attendre quelques minutes ou d'utiliser le tableau de bord.

## Erreurs

### Erreurs HTTP

Elles sont renvoyées comme statut HTTP de la requête, avec un corps JSON contenant `code`.

| Statut | Code | Quand | Que faire |
| - | - | - | - |
| `401` | `ACCESS_DENIED` | Aucune clé, ou la clé est erronée, révoquée ou expirée. La réponse contient la demande d'authentification OAuth, donc Claude et ChatGPT vous demandent de vous reconnecter. | Reconnectez le client, ou créez une nouvelle [clé API](https://docs.squarecloud.app/fr/mcp/connect.md#créer-une-clé-api). |
| `403` | `ACCESS_DENIED` | Un jeton de session du tableau de bord a été envoyé au lieu d'une clé API. | Connectez-vous avec OAuth ou avec une clé API. |
| `403` | `MISSING_SCOPE` | La clé n'a pas le scope `mcp`. Également renvoyé lorsqu'une clé Claude ou ChatGPT est utilisée sur l'API REST. | Créez une clé avec `mcp`. |
| `403` | `UPGRADE_REQUIRED` | Le compte n'a aucun plan actif. | Souscrivez ou renouvelez un [plan](https://docs.squarecloud.app/fr/platform/plans.md). |
| `421` | `WRONG_HOST` | La requête est allée vers une autre adresse Square Cloud, comme `api.squarecloud.app`. | Utilisez `https://mcp.squarecloud.app/mcp`. |
| `429` | `RATE_LIMITED` | La limite de requêtes vers le serveur MCP a été dépassée, ou le compte est bloqué par sa limite de débit de l'API. | Attendez une minute et ralentissez le client. |
| `400` | Erreur JSON-RPC | Une version du protocole non prise en charge (`-32022`, avec la liste des versions prises en charge) ou une requête mal formée. | Mettez à jour le client. |

### Lors de la connexion

| Ce que vous voyez | Pourquoi | Que faire |
| - | - | - |
| `UNKNOWN_CLIENT` ou `INVALID_REDIRECT_URI` sur une page de `mcp.squarecloud.app` | Seuls Claude, avec son identité publiée, et ChatGPT se connectent avec OAuth. | Dans Claude, choisissez **Use Claude's published identity**. Dans les autres clients, connectez-vous avec une [clé API](https://docs.squarecloud.app/fr/mcp/connect.md#créer-une-clé-api). |
| `The account is at its API key limit` | Le compte a déjà 10 clés. | Révoquez une clé dans les [paramètres de sécurité de votre compte](https://squarecloud.app/fr/account/security) et connectez-vous à nouveau. |
| La page de consentement indique que la demande a expiré | Elle est valable 10 minutes. | Relancez la connexion depuis le client. |

### Résultats des outils

Ils sont renvoyés dans un résultat d'outil, sous forme de `code`, à côté d'un `summary` que lit le client.

| Code | Signification | Que faire |
| - | - | - |
| `SNAPSHOT_NOT_READY` | Le [snapshot de sécurité](https://docs.squarecloud.app/fr/mcp/permissions-and-safety.md#suppressions-et-restaurations) pris avant une suppression, une restauration ou un `commit_application` avec `snapshot` est encore en cours de génération. Rien ne s'est exécuté. | Le client réessaie avec les mêmes arguments dans 2 minutes environ. |
| `MISSING_SCOPE` | Cet appel nécessite un scope que la clé n'a pas, comme `databases:read` pour les métriques d'une base de données. | Utilisez une clé qui a ce scope. |
| `RESOURCE_NOT_ALLOWED` | La clé est restreinte à d'autres applications et bases de données, ou aucune de celles qu'elle couvre ne porte ce nom. | Utilisez une clé qui couvre la ressource. |
| `TOOL_RATE_LIMITED` | Une [limite](#limites) a été atteinte. | Attendez le temps indiqué dans le résumé. |
| `TOOL_EXECUTION_FAILED` | Le même outil a atteint une limite deux fois de suite, ou il a échoué. | Attendez quelques minutes ou utilisez le tableau de bord. |
| `APP_NOT_FOUND`, `DATABASE_NOT_FOUND` | Aucune application ou base de données ne correspond au nom ou à l'ID. | Demandez au client de les lister d'abord. |
| `INVALID_ZIP` | `zip` n'est pas en base64, ou le zip est endommagé. | Recréez le zip et renvoyez-le. |
| `ZIP_TOO_LARGE` | Le zip dépasse 1 Mo, ou 100 Mo une fois décompressé. | Envoyez un zip plus petit, ou déployez le projet avec la [CLI](https://docs.squarecloud.app/fr/cli-reference/deploy.md) ou depuis le tableau de bord. |
| `MISSING_MANIFEST` | Le zip de `upload_application` n'a pas de `squarecloud.app` à sa racine, souvent parce que le projet se trouve dans un dossier du zip. | Compressez le contenu du dossier, avec `squarecloud.app` (`DISPLAY_NAME`, `MAIN`, `MEMORY`, `VERSION`) à la racine. |
| `BLOCKED_PATH` | Un chemin pointe hors du dossier de destination, ou le zip contient des fichiers dans le dossier `.squarecloud`, qui appartient à la plateforme et ne peut pas être modifié. Dans `files`, les fichiers cachés, les fichiers `.env`, les clés privées et le fichier de configuration sont aussi refusés. | Retirez ces fichiers et envoyez à nouveau. |
| `INVALID_PATH` | `path` n'est pas un dossier dans lequel un commit peut écrire. | Choisissez un autre dossier de l'application. |
| `RESTORE_IN_PROGRESS` | Une restauration est en cours sur l'application. | Attendez qu'elle se termine, puis réessayez. |
| `RATE_LIMITED` | Un commit est arrivé trop tôt après le précédent. | Attendez quelques secondes et réessayez. |
| `COMMIT_FAILED` | La nouvelle version n'a pas pu être écrite dans l'application. | Réessayez, ou envoyez-la depuis le tableau de bord. |

Un outil que votre clé ne peut pas utiliser, ou qui n'existe pas, répond l'erreur JSON-RPC `-32602` `Unknown tool`. Vérifiez les [scopes](https://docs.squarecloud.app/fr/mcp/permissions-and-safety.md#scopes) de la clé. Les autres codes viennent de l'outil lui-même, et le `summary` les explique.


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