SDK JavaScript: errori e retry

Ogni errore dell’API, di rete e locale lancia un’unica classe: SquareCloudAPIError. Gli esempi usano il client api di Creare il client. appId è l’id di una delle tue app: api.account.me() le elenca.

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 estende Error (non è un TypeError).

Proprietà	Tipo	Descrizione
`status`	`number`	Status HTTP. `0` quando non è arrivata alcuna risposta (errore di rete, timeout, controllo locale)
`code`	`ErrorCode`	Il codice di errore dell’API, ad es. `APP_NOT_FOUND`, oppure uno dei codici dell’SDK
`message`	`string`	La spiegazione del server. Quando il server ha inviato solo un codice, il codice stesso
`method`	`string`	Metodo HTTP della chiamata fallita
`path`	`string`	Percorso dell’URL della chiamata fallita, senza query string
`cause`	`unknown`	L’errore originale, per `NETWORK_ERROR` e JSON non valido

Due errori non vengono incapsulati:

Una chiamata annullata viene rifiutata con il reason del signal. Un ciclo realtime() annullato semplicemente termina.
Un percorso di upload che non può essere aperto lancia l’errore del file system.

Codici dell’SDK

Status	Codice	Quando
0	`NETWORK_ERROR`	Nessuna risposta (DNS, connessione reimpostata, body troncato). L’errore originale è in `cause`
0	`TIMEOUT`	Nessuna risposta entro il timeout
0	`FILE_TOO_LARGE`	Controllo locale: un upload oltre 100 MB o un `files.write` oltre 10 MB. Non è stato inviato nulla
0	`INVALID_ID`	Controllo locale: un id vuoto, `.` o `..`. Non è stato inviato nulla
qualsiasi	`UNKNOWN_ERROR`	Una risposta senza codice (come la pagina di errore di un proxy), con lo `status` reale e il messaggio `HTTP <status>`. Un body 2xx che non è JSON ha il messaggio `Invalid JSON in HTTP <status> response`

Il tipo `ErrorCode`

ErrorCode è solo un tipo (nessun oggetto a runtime). Elenca ogni codice pubblico dell’API, quelli deprecati e quelli dell’SDK, più string & {}, così il tuo editor completa automaticamente i codici noti e i nuovi codici superano comunque il controllo dei tipi. RATE_LIMIT e RATE_LIMIT_EXCEEDED sono ancora presenti nel tipo, contrassegnati come deprecati: l’API ora risponde RATE_LIMITED per entrambi. L’elenco dei codici dell’API cresce. Gestisci un codice sconosciuto in base al suo status 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;
        }
    }
}

Codici di errore dell’API

Ogni altro codice proviene dall’API. Il riferimento degli errori dell’API li elenca uno per uno con lo status HTTP, il significato e la soluzione, e ogni pagina degli SDK elenca i codici che i suoi metodi restituiscono più spesso. Qualsiasi chiamata può anche rispondere 401 ACCESS_DENIED (una chiave errata), 403 MISSING_SCOPE o RESOURCE_NOT_ALLOWED (i limiti della chiave), 429 (vedi Rate limit) o 503 DATABASE_UNAVAILABLE. Gli errori di ai.chat() usano invece i codici minuscoli di OpenAI (access_denied, rate_limit_exceeded, server_overloaded, …). Vedi AI.

Retry

L’SDK ripete solo ciò che è sicuro ripetere, fino a maxRetries volte (predefinito 2, quindi fino a 3 tentativi):

Ripetuto	Metodi
`NETWORK_ERROR`	Solo `GET`
503 `UPLOAD_BUSY`	Qualsiasi metodo
503 `ANALYTICS_BUSY`	Qualsiasi metodo
503 `DATABASE_UNAVAILABLE`	Solo `GET`

Non ripete mai:

TIMEOUT;
qualsiasi 429: RATE_LIMITED può essere un blocco di circa 30 minuti, e nemmeno KEEP_CALM viene ripetuto;
gli altri 5xx;
gli errori dell’AI.

503 DATABASE_UNAVAILABLE può arrivare dopo che una mutazione è già stata applicata, quindi l’SDK non lo ripete al di fuori di GET. Ripeti tu le tue mutazioni idempotenti, se necessario. L’attesa prima del retry n (a partire da 0) è min(8 s, 500 ms · 2^n) · U(0.5, 1): backoff esponenziale con jitter dal 50% al 100%. Imposta maxRetries: 0 per disattivare i retry.

Timeout

timeoutMs (30 s) si applica per tentativo e copre l’intera risposta. Vedi Timeout per le chiamate con una soglia minima di 120 s e quelle senza timeout. Un timeout lancia TIMEOUT con status 0 e non viene mai ripetuto.

Rate limit

Ogni account ha un limite di richieste ogni 60 secondi, stabilito dal suo piano (valori), e alcune route hanno un limite proprio:

429 RATE_LIMITED: l’account o la chiave API ha superato il suo budget di richieste ed è bloccato per circa 30 minuti, oppure un IP che continua a inviare chiavi non valide viene bloccato per un breve periodo. È anche il limite degli endpoint di rete e di account.snapshots.
429 KEEP_CALM: troppe chiamate a una route in poco tempo.

L’SDK non ripete mai un 429. Rallenta e attendi prima di riprovare.

Prossimi passi

Riferimento degli errori dell'API

Ogni codice di errore, con il significato e la soluzione.

Limiti e restrizioni

I limiti di richieste di ogni piano.

CLI

VS Code

SDKs

SDK JavaScript: errori e retry

`SquareCloudAPIError`

Codici dell’SDK

Il tipo `ErrorCode`

Codici di errore dell’API

Retry

Timeout

Rate limit

Prossimi passi

Riferimento degli errori dell'API

Limiti e restrizioni

​SquareCloudAPIError

​Codici dell’SDK

​Il tipo ErrorCode

​Codici di errore dell’API

​Retry

​Timeout

​Rate limit

​Prossimi passi

Riferimento degli errori dell'API

Limiti e restrizioni

`SquareCloudAPIError`

Codici dell’SDK

Il tipo `ErrorCode`

Codici di errore dell’API

Retry

Timeout

Rate limit

Prossimi passi