> ## 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. # SDK JavaScript : erreurs et nouvelles tentatives > Gérez SquareCloudAPIError dans @squarecloud/api : statut, code et message, codes propres au SDK, nouvelles tentatives, timeouts et limites de débit. Chaque échec de l'API, du réseau ou local lève une seule classe : `SquareCloudAPIError`. Les exemples utilisent le client `api` présenté dans [Créer le client](/fr/sdks/js/client#créer-le-client). `appId` est l'identifiant de l'une de vos applications : [`api.account.me()`](/fr/sdks/js/client#compte) les liste. ```typescript theme={"system"} import { SquareCloudAPI, SquareCloudAPIError } from "@squarecloud/api"; try { await api.apps.start(appId); } catch (error) { if (error instanceof SquareCloudAPIError) { console.error(error.status, error.code, error.message); console.error(error.method, error.path); // "POST" "/v2/apps//start" } } ``` ## `SquareCloudAPIError` `SquareCloudAPIError` étend `Error` (ce n'est **pas** une `TypeError`). | Propriété | Type | Description | | - | - | - | | `status` | `number` | Statut HTTP. `0` lorsqu'aucune réponse n'est arrivée (erreur réseau, timeout, vérification locale) | | `code` | `ErrorCode` | Le code d'erreur de l'API, par ex. `APP_NOT_FOUND`, ou l'un des codes du SDK | | `message` | `string` | L'explication du serveur. Lorsque le serveur n'a envoyé qu'un code, le code lui-même | | `method` | `string` | Méthode HTTP de l'appel échoué | | `path` | `string` | Chemin de l'URL de l'appel échoué, sans la chaîne de requête | | `cause` | `unknown` | L'erreur d'origine, pour `NETWORK_ERROR` et un JSON invalide | Deux échecs ne sont pas encapsulés : * Un appel annulé est rejeté avec la `reason` du signal. Une boucle `realtime()` annulée se termine simplement. * Un chemin d'envoi qui ne peut pas être ouvert lève l'erreur du système de fichiers. ## Codes du SDK | Statut | Code | Quand | | - | - | - | | 0 | `NETWORK_ERROR` | Aucune réponse (DNS, connexion réinitialisée, corps tronqué). L'erreur d'origine se trouve dans `cause` | | 0 | `TIMEOUT` | Aucune réponse dans le [timeout](/fr/sdks/js/client#timeouts) | | 0 | `FILE_TOO_LARGE` | Vérification locale : un envoi de plus de 100 Mo ou un `files.write` de plus de 10 Mo. Rien n'a été envoyé | | 0 | `INVALID_ID` | Vérification locale : un identifiant vide, `.` ou `..`. Rien n'a été envoyé | | tous | `UNKNOWN_ERROR` | Une réponse sans code (comme une page d'erreur de proxy), avec le vrai `status` et le message `HTTP `. Un corps 2xx qui n'est pas du JSON a le message `Invalid JSON in HTTP response` | ## Le type `ErrorCode` `ErrorCode` est **uniquement un type** (aucun objet à l'exécution). Il liste tous les codes publics de l'API, les codes dépréciés et ceux du SDK, plus `string & {}`, de sorte que votre éditeur complète automatiquement les codes connus et que les nouveaux codes passent toujours la vérification de types. `RATE_LIMIT` et `RATE_LIMIT_EXCEEDED` figurent toujours dans le type, marqués comme dépréciés : l'API répond désormais `RATE_LIMITED` pour les deux. La liste des codes de l'API s'allonge. **Traitez un code inconnu d'après son statut HTTP** : ```typescript theme={"system"} async function start(appId: string) { try { await api.apps.start(appId); } catch (error) { if (!(error instanceof SquareCloudAPIError)) throw error; switch (error.code) { case "APP_NOT_FOUND": return null; case "CONTAINER_ALREADY_STARTED": return; // fine default: if (error.status === 429) return retryLater(); if (error.status >= 500) return reportOutage(error); throw error; } } } ``` ## Codes d'erreur de l'API Tous les autres codes viennent de l'API. La [référence des erreurs de l'API](/fr/api-reference/errors) liste chacun d'eux avec son statut HTTP, sa signification et sa solution, et chaque page du SDK liste les codes que ses méthodes renvoient le plus souvent. N'importe quel appel peut aussi répondre 401 `ACCESS_DENIED` (une clé invalide), 403 `MISSING_SCOPE` ou `RESOURCE_NOT_ALLOWED` (les [limites de la clé](/fr/sdks/js/client#clé-api-et-scopes)), 429 (voir [Limites de débit](#limites-de-débit)) ou 503 `DATABASE_UNAVAILABLE`. Les erreurs de `ai.chat()` utilisent plutôt les codes OpenAI en minuscules (`access_denied`, `rate_limit_exceeded`, `server_overloaded`, ...). Voir [IA](/fr/sdks/js/ai#erreurs). ## Nouvelles tentatives Le SDK ne réessaie que ce qui peut être répété sans risque, jusqu'à `maxRetries` fois (par défaut `2`, soit jusqu'à 3 tentatives) : | Réessayé | Méthodes | | - | - | | `NETWORK_ERROR` | `GET` uniquement | | 503 `UPLOAD_BUSY` | Toute méthode | | 503 `ANALYTICS_BUSY` | Toute méthode | | 503 `DATABASE_UNAVAILABLE` | `GET` uniquement | Il ne réessaie **jamais** : * `TIMEOUT` ; * aucun **429** : `RATE_LIMITED` peut être un blocage d'environ 30 minutes, et `KEEP_CALM` n'est pas réessayé non plus ; * les autres 5xx ; * les erreurs d'IA. 503 `DATABASE_UNAVAILABLE` peut arriver alors qu'une mutation a déjà été appliquée : le SDK ne la réessaie donc pas en dehors de `GET`. Réessayez vous-même vos mutations idempotentes si nécessaire. L'attente avant la nouvelle tentative `n` (à partir de 0) est `min(8 s, 500 ms · 2^n) · U(0.5, 1)` : un backoff exponentiel avec un jitter de 50 % à 100 %. Définissez `maxRetries: 0` pour désactiver les nouvelles tentatives. ## Timeouts `timeoutMs` (30 s) s'applique par tentative et couvre toute la réponse. Voir [Timeouts](/fr/sdks/js/client#timeouts) pour les appels avec un plancher de 120 s et les appels sans timeout. Un timeout lève `TIMEOUT` avec le statut `0` et n'est jamais réessayé. ## Limites de débit Chaque compte dispose d'une limite de requêtes par 60 secondes, fixée par son plan ([valeurs](/fr/api-reference/limitations-and-restrictions)), et certaines routes ont la leur : * **429 `RATE_LIMITED`** : le compte ou la clé API a dépassé son budget de requêtes et est bloqué pendant environ 30 minutes, ou une IP qui envoie sans cesse des clés invalides est bloquée pendant une courte période. C'est aussi la limite des endpoints réseau et de `account.snapshots`. * **429 `KEEP_CALM`** : trop d'appels vers une même route en peu de temps. Le SDK ne réessaie jamais un 429. Ralentissez, et attendez avant de réessayer. ## Prochaines étapes Chaque code d'erreur, avec sa signification et sa solution. Les limites de requêtes de chaque plan. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.