*squarecloud.APIError. Inspecione-o com errors.As.
Os trechos mais curtos abaixo rodam dentro do programa de Executando os exemplos: cole um de cada vez em main e execute o goimports.
APIError
Unwrap() retorna a causa (o erro de transporte, de decodificação ou do context) para NETWORK_ERROR, TIMEOUT e JSON inválido, ou nil. Error() gera squarecloud: <METHOD> <path>: HTTP <status> <CODE>: <message>, sem HTTP <status> quando o status é 0 e sem : <message> quando ela está vazia. Compare pelos campos, não por esse texto.
Contexts cancelados e expirados
Uma chamada cujoctx é cancelado retorna um *APIError com NETWORK_ERROR, e uma cujo prazo expira retorna TIMEOUT, ambos com status 0. Eles fazem unwrap para o erro do context:
*APIError:
Realtime.Nextretorna octx.Err()puro quando seuctxtermina, eio.EOFquando o stream termina normalmente.- Problemas do lado de quem chama são erros simples: um reader de upload
nil, uma URL de snapshot ou URL base que não pode ser interpretada, uma entrada que oencoding/jsonnão consegue codificar e um erro doio.Writerpassado paraDownloadSnapshot.
Códigos do SDK
Constantes Code*
Code é uma string simples. O pacote tem uma constante por código público da API, nomeada a partir dele no estilo Go (CodeAppNotFound para APP_NOT_FOUND, CodeInvalidID, CodeDNSFailed, …), além dos códigos próprios do SDK acima. CodeRateLimit (RATE_LIMIT) e CodeRateLimitExceeded (RATE_LIMIT_EXCEEDED) continuam exportadas, marcadas como depreciadas: a API agora responde RATE_LIMITED (CodeRateLimited) para os dois.
A lista de códigos da API cresce. Trate um código desconhecido pelo seu status HTTP:
Códigos de erro da API
Todos os outros códigos vêm da API. A referência de erros da API lista cada um com o status HTTP, o significado e a solução, e cada página do SDK lista os códigos que os seus métodos retornam com mais frequência. Qualquer chamada também pode responder 401ACCESS_DENIED (uma chave inválida), 403 MISSING_SCOPE ou RESOURCE_NOT_ALLOWED (os limites da chave), 429 (veja Rate limits) ou 503 DATABASE_UNAVAILABLE.
Os erros de AI.Chat usam, em vez disso, códigos da OpenAI em minúsculas (access_denied, rate_limit_exceeded, server_overloaded, …), que Code carrega literalmente. Veja IA.
Novas tentativas
O SDK só tenta novamente o que é seguro repetir, atéWithMaxRetries vezes (padrão 2, ou seja, até 3 tentativas):
Ele nunca tenta novamente:
TIMEOUT;- qualquer 429:
RATE_LIMITEDpode ser um bloqueio de cerca de 30 minutos, eKEEP_CALMtambém não é repetido; - outros 5xx;
- erros de IA.
DATABASE_UNAVAILABLE pode chegar depois que uma mutação já foi aplicada, então o SDK não o repete fora de GET. Repita suas próprias mutações idempotentes se precisar. Um upload só é repetido quando seu corpo pode ser reenviado: um io.ReaderAt com tamanho conhecido, como um *os.File (veja Commit e upload).
A espera antes da nova tentativa n (começando em 0) é min(8 s, 500 ms · 2^n) · U(0.5, 1): backoff exponencial com jitter de 50% a 100%. Defina WithMaxRetries(0) para desativar as novas tentativas.
Timeouts
WithTimeout (30 s) se aplica apenas quando o ctx não tem prazo, e um único prazo cobre a chamada inteira, incluindo as novas tentativas e as esperas de backoff. Veja Timeouts para as chamadas com mínimo de 2 minutos e as chamadas sem prazo padrão. Um prazo que expira retorna TIMEOUT com status 0, nunca é repetido e faz unwrap para context.DeadlineExceeded.
Rate limits
Toda conta tem um limite de requisições a cada 60 segundos, definido pelo seu plano (valores), e algumas rotas têm limites próprios:- 429
RATE_LIMITED: a conta ou a chave de API ultrapassou a sua cota de requisições e fica bloqueada por cerca de 30 minutos, ou um IP que continua enviando chaves inválidas fica bloqueado por um curto período. Também é o limite dos endpoints de rede e deAccount.Snapshots. - 429
KEEP_CALM: chamadas demais a uma rota em pouco tempo.
Próximos passos
Referência de erros da API
Todos os códigos de erro, com o significado e a solução.
Limitações e restrições
Os limites de requisições de cada plano.

