SDK JavaScript : erreurs et nouvelles tentatives

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. appId est l’identifiant de l’une de vos applications : api.account.me() les liste.

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/<id>/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
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 <status>`. Un corps 2xx qui n’est pas du JSON a le message `Invalid JSON in HTTP <status> 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 :

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 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é), 429 (voir 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.

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 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), 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.

CLI

VS Code

SDKs

SDK JavaScript : erreurs et nouvelles tentatives

`SquareCloudAPIError`

Codes du SDK

Le type `ErrorCode`

Codes d’erreur de l’API

Nouvelles tentatives

Timeouts

Limites de débit

Prochaines étapes

Référence des erreurs de l'API

Limitations et restrictions

​SquareCloudAPIError

​Codes du SDK

​Le type ErrorCode

​Codes d’erreur de l’API

​Nouvelles tentatives

​Timeouts

​Limites de débit

​Prochaines étapes

Référence des erreurs de l'API

Limitations et restrictions

`SquareCloudAPIError`

Codes du SDK

Le type `ErrorCode`

Codes d’erreur de l’API

Nouvelles tentatives

Timeouts

Limites de débit

Prochaines étapes