*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 cuictx 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:
*APIError:
Realtime.Nextrestituisce il semplicectx.Err()quando il suoctxtermina, eio.EOFquando 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 cheencoding/jsonnon riesce a codificare e un errore dell’io.Writerpassato aDownloadSnapshot.
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 401ACCESS_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 aWithMaxRetries volte (predefinito 2, quindi fino a 3 tentativi):
Non ripete mai:
TIMEOUT;- qualsiasi 429:
RATE_LIMITEDpuò essere un blocco di circa 30 minuti, e nemmenoKEEP_CALMviene ripetuto; - gli altri 5xx;
- gli errori dell’AI.
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 diAccount.Snapshots. - 429
KEEP_CALM: troppe chiamate a una route in poco tempo.
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.

