SDK Python: errori e retry

Ogni errore dell’API e di rete solleva un’unica eccezione: SquareCloudAPIError. Gli esempi usano il client di Creare il client. app_id è l’id di una delle tue app: client.account.me() le elenca.

from squarecloud import SquareCloudAPIError

try:
    client.apps.start(app_id)
except SquareCloudAPIError as error:
    print(error.status, error.code, error.message)
    print(error.method, error.path)  # "POST" "/v2/apps/<id>/start"
    print(error)  # POST /v2/apps/<id>/start: HTTP 404 APP_NOT_FOUND

`SquareCloudAPIError`

SquareCloudAPIError è una sottoclasse di Exception.

Attributo	Tipo	Descrizione
`status`	`int`	Status HTTP. `0` quando non è arrivata alcuna risposta (errore di rete, timeout, controllo locale)
`code`	`str`	Il codice di errore dell’API, ad es. `APP_NOT_FOUND`, oppure uno dei codici dell’SDK
`message`	`str`	La spiegazione del server. `''` quando il server ha inviato solo un codice
`method`	`str`	Metodo HTTP della chiamata fallita
`path`	`str`	Percorso dell’URL della chiamata fallita, senza query string
`cause`	`BaseException \| None`	L’eccezione originale, per `NETWORK_ERROR`, `TIMEOUT` e JSON non valido (la stessa di `__cause__`)

str(error) è <METHOD> <path>: HTTP <status> <CODE>: <message>, senza HTTP <status> quando lo status è 0 e senza : <message> quando il messaggio è vuoto. Due errori non vengono incapsulati:

Una chiave API vuota o composta solo da spazi solleva un ValueError nel costruttore del client.
I problemi con i file locali sollevano un OSError: un percorso di upload che non può essere aperto, un file che diventa illeggibile durante l’upload o una destinazione di download_snapshot in cui non è possibile scrivere.

Codici dell’SDK

Status	Codice	Quando
0	`NETWORK_ERROR`	Nessuna risposta (DNS, connessione reimpostata, body troncato). L’eccezione originale è in `cause`
0	`TIMEOUT`	Un’operazione sul socket ha superato 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 del server, oppure `HTTP <status>` quando non ce n’è uno. Un body 2xx che non è JSON ha il messaggio `Invalid JSON in HTTP <status> response`

I codici sono stringhe

code è una semplice str: l’SDK non ha un enum dei codici. La docstring di SquareCloudAPIError elenca ogni codice noto dell’API. RATE_LIMIT e RATE_LIMIT_EXCEEDED sono ancora elencati lì, 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:

def start(app_id: str):
    try:
        client.apps.start(app_id)
    except SquareCloudAPIError as error:
        match error.code:
            case "APP_NOT_FOUND":
                return None
            case "CONTAINER_ALREADY_STARTED":
                return  # fine
            case _:
                if error.status == 429:
                    return retry_later()
                if error.status >= 500:
                    return report_outage(error)
                raise

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 max_retries 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 max_retries=0 per disattivare i retry.

Timeout

timeout (30 s) si applica per operazione sul socket (la connessione e ogni lettura o scrittura), non all’intera richiesta. Vedi Timeout per le chiamate con una soglia minima di 120 s e quelle senza timeout. Un timeout solleva 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 Python: errori e retry

`SquareCloudAPIError`

Codici dell’SDK

I codici sono stringhe

Codici di errore dell’API

Retry

Timeout

Rate limit

Prossimi passi

Riferimento degli errori dell'API

Limiti e restrizioni

​SquareCloudAPIError

​Codici dell’SDK

​I codici sono stringhe

​Codici di errore dell’API

​Retry

​Timeout

​Rate limit

​Prossimi passi

Riferimento degli errori dell'API

Limiti e restrizioni

`SquareCloudAPIError`

Codici dell’SDK

I codici sono stringhe

Codici di errore dell’API

Retry

Timeout

Rate limit

Prossimi passi