Errori

Ogni errore dell’API, di rete e locale lancia un’unica classe: SquareCloudAPIError.

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. L’elenco dei codici dell’API cresce. Gestisci un codice sconosciuto in base al suo status HTTP:

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;
    }
}

Errori di qualsiasi chiamata

Status	Codice	Quando
401	`ACCESS_DENIED`	Chiave API mancante, sconosciuta, revocata o scaduta
403	`MISSING_SCOPE`	Alla chiave manca lo scope di questa chiamata. `message` lo indica
403	`RESOURCE_NOT_ALLOWED`	La chiave è limitata ad altre app o database
403	`PERMISSION_DENIED`	Il tuo ruolo nel workspace non consente l’azione
404	`ROUTE_NOT_FOUND`	Route sconosciuta
429	`RATE_LIMITED`	Blocco dell’account, della chiave o dell’IP (può durare circa 30 min), e limite degli endpoint di rete e di `account.snapshots`
429	`KEEP_CALM`	Troppo veloce per questa route
500	`INTERNAL_SERVER_ERROR`	Errore del server
503	`DATABASE_UNAVAILABLE`	Il database della piattaforma non è disponibile. Una mutazione potrebbe essere già stata applicata

Codici dell’API per gruppo

Non trovato

APP_NOT_FOUND, DATABASE_NOT_FOUND, WORKSPACE_NOT_FOUND, MEMBER_NOT_FOUND, FILE_NOT_FOUND, SNAPSHOT_NOT_FOUND, REPOSITORY_NOT_FOUND, BRANCH_NOT_FOUND, ROUTE_NOT_FOUND

Validazione

INVALID_ACCESS_TOKEN, INVALID_AUTORESTART, INVALID_BRANCH_LENGTH, INVALID_CODE, INVALID_CONTENT, INVALID_CONTENT_TYPE, INVALID_DATABASE_TYPE, INVALID_DATABASE_VERSION, INVALID_DESCRIPTION, INVALID_DISPLAY_NAME, INVALID_DOMAIN, INVALID_ENCODING, INVALID_ENV_CONTENT, INVALID_FILE, INVALID_FILENAME, INVALID_FILTER, INVALID_GROUP, INVALID_ID, INVALID_INPUT, INVALID_JSON_BODY, INVALID_MEMORY, INVALID_NAME, INVALID_PARAMETERS, INVALID_PATH, INVALID_RESET_TYPE, INVALID_SCOPE, INVALID_SNAPSHOT_ID, INVALID_SUBDOMAIN, INVALID_TIME_RANGE, INVALID_VERSION_ID, MISSING_PARAMETERS, MISSING_REQUIRED_FIELDS, NO_UPDATE_DATA, VALIDATION_FAILED, VALIDATION_TIMEOUT, ENV_NAME_TOO_LONG, ENV_CONTENT_TOO_LONG, TOO_MANY_ENV_VARS, RESERVED_DOMAIN, CANNOT_SET_SUBDOMAIN, STATIC_APP_ENV_NOT_SUPPORTED

Autenticazione e permessi

ACCESS_DENIED, MISSING_SCOPE, RESOURCE_NOT_ALLOWED, PERMISSION_DENIED, SCOPE_NOT_GRANTABLE, BLOCKED_PATH, UPGRADE_REQUIRED

Limiti e rate limit

RATE_LIMITED, KEEP_CALM, APPLICATIONS_LIMIT_REACHED, WORKSPACE_LIMIT_REACHED, MEMBERS_LIMIT_REACHED, LOAD_BALANCER_LIMIT_REACHED, DAILY_SNAPSHOTS_LIMIT_REACHED, INSUFFICIENT_MEMORY, FILE_TOO_LARGE, PAYLOAD_TOO_LARGE, REALTIME_MAX_CONNECTIONS, REALTIME_MAX_CONNECTIONS_APP, AI_DAILY_LIMIT_REACHED, AI_MAX_CONCURRENT_STREAMS, AI_NO_PLAN_LIMIT_REACHED

Container (avvio, arresto, riavvio)

CONTAINER_ALREADY_STARTED, CONTAINER_ALREADY_STOPPED, CONTAINER_TEMPORARILY_SUSPENDED, CONTAINER_NOT_FOUND, CONTAINER_INSUFFICIENT_DISK_SPACE, CONTAINER_NETWORK_CONFLICT, ACTION_FAILED, DATABASE_NOT_RUNNING

Upload, file e commit

UPLOAD_BUSY, UPLOAD_FAILED, UPLOAD_ABORTED, STORAGE_UPLOAD_FAILED, COMMIT_FAILED, READ_FAILED, SAVE_FAILED, RENAME_FAILED, DELETE_FAILED, REQUEST_ABORTED, EMPTY_RESPONSE

Snapshot

SNAPSHOT_FAILED, SNAPSHOT_PROCESSING, SNAPSHOT_RESTORE_FAILED, SNAPSHOT_DATABASE_MISMATCH, RESTORE_IN_PROGRESS

Deploy e GitHub

GIT_ALREADY_CONFIGURED, GIT_NOT_CONFIGURED, GITHUB_NOT_CONNECTED, REPOSITORY_BRANCH_ALREADY_CONFIGURED, REPOSITORY_NOT_AVAILABLE, REPOSITORY_PERMISSION_REQUIRED, FAILED_TO_FETCH

Rete e domini

ANALYTICS_BUSY, UNABLE_TO_FETCH_ANALYTICS, UNABLE_TO_FETCH_ERRORS, UNABLE_TO_FETCH_PERFORMANCE, DNS_FAILED, DOMAIN_ALREADY_EXISTS, NO_CUSTOM_DOMAIN, PURGE_CACHE_FAILED, LOGS_UNAVAILABLE, METRICS_NOT_SUPPORTED

Database e workspace

DATABASE_CREATION_FAILED, DATABASE_UNAVAILABLE, RESET_FAILED, WORKSPACE_CREATION_FAILED, APP_ALREADY_IN_WORKSPACE, MEMBER_ALREADY_ADDED, CANNOT_EDIT_OWNER, CANNOT_INVITE_OWNER, CANNOT_LEAVE_OWNER, CONFLICTING_RESOURCES

Piattaforma

INTERNAL_SERVER_ERROR, CLUSTER_MAINTENANCE_TRY_LATER, CLUSTER_SELECTION_FAILED, CLUSTER_TIMEOUT, CLUSTER_UNAVAILABLE, AI_UNAVAILABLE

Deprecati

RATE_LIMIT e RATE_LIMIT_EXCEEDED sono ancora presenti nel tipo, contrassegnati come deprecati: l’API ora risponde RATE_LIMITED per entrambi.

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: un blocco dell’account, della chiave API o dell’IP, che può durare circa 30 minuti. È 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.

Servizi

Runtimes

Piattaforma

Risoluzione dei problemi

CLI

SDKs

Changelog

`SquareCloudAPIError`

Codici dell’SDK

Il tipo `ErrorCode`

Errori di qualsiasi chiamata

Codici dell’API per gruppo

Retry

Timeout

Rate limit

​SquareCloudAPIError

​Codici dell’SDK

​Il tipo ErrorCode

​Errori di qualsiasi chiamata

​Codici dell’API per gruppo

​Retry

​Timeout

​Rate limit

`SquareCloudAPIError`

Codici dell’SDK

Il tipo `ErrorCode`

Errori di qualsiasi chiamata

Codici dell’API per gruppo

Retry

Timeout

Rate limit