Skip to main content
Ogni errore dell’API, di rete e locale è di un unico tipo: *squarecloud.APIError. Ispezionalo con errors.As. Gli snippet più brevi qui sotto funzionano all’interno del programma di Eseguire gli esempi: incollane uno alla volta in main ed esegui goimports.

APIError

Unwrap() restituisce la causa (l’errore di trasporto, di decodifica o del context) per NETWORK_ERROR, TIMEOUT e JSON non valido, altrimenti nil. Error() produce squarecloud: <METHOD> <path>: HTTP <status> <CODE>: <message>, senza HTTP <status> quando lo status è 0 e senza : <message> quando è vuoto. Basati sui campi, non su questo testo.

Context annullati e scaduti

Una chiamata il cui ctx viene annullato restituisce un *APIError con NETWORK_ERROR, e una la cui scadenza passa restituisce TIMEOUT, entrambi con status 0. Entrambi fanno l’unwrap all’errore del context:
Alcuni fallimenti non sono *APIError:
  • Realtime.Next restituisce il semplice ctx.Err() quando il suo ctx termina, e io.EOF quando il flusso termina normalmente.
  • I problemi dal lato del chiamante sono errori semplici: un reader di upload nil, un URL di snapshot o un URL base che non può essere analizzato, un input che encoding/json non riesce a codificare e un errore dell’io.Writer passato a DownloadSnapshot.

Codici dell’SDK

Costanti Code*

Code è una semplice string. Il package ha una costante per ogni codice pubblico dell’API, con il nome in stile Go (CodeAppNotFound per APP_NOT_FOUND, CodeInvalidID, CodeDNSFailed, …), più i codici propri dell’SDK elencati sopra. CodeRateLimit (RATE_LIMIT) e CodeRateLimitExceeded (RATE_LIMIT_EXCEEDED) sono ancora esportati, contrassegnati come deprecati: l’API ora risponde RATE_LIMITED (CodeRateLimited) per entrambi. L’elenco dei codici dell’API cresce. Gestisci un codice sconosciuto in base al suo status HTTP:

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, …), che Code riporta testualmente. Vedi AI.

Retry

L’SDK ripete solo ciò che è sicuro ripetere, fino a WithMaxRetries volte (predefinito 2, quindi fino a 3 tentativi): 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. Un upload viene ripetuto solo quando il suo body può essere riprodotto: un io.ReaderAt con dimensione nota, come un *os.File (vedi Commit e upload). 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 WithMaxRetries(0) per disattivare i retry.

Timeout

WithTimeout (30 s) si applica solo quando ctx non ha una scadenza, e una sola scadenza copre l’intera chiamata, compresi i retry e le attese di backoff. Vedi Timeout per le chiamate con una soglia minima di 2 minuti e quelle senza scadenza predefinita. Una scadenza superata restituisce TIMEOUT con status 0, non viene mai ripetuta e fa l’unwrap a context.DeadlineExceeded.

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.