Skip to main content
Toda falha da API, de rede ou local é de um único tipo: *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 cujo ctx é 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:
Algumas falhas não são *APIError:
  • Realtime.Next retorna o ctx.Err() puro quando seu ctx termina, e io.EOF quando 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 o encoding/json não consegue codificar e um erro do io.Writer passado para DownloadSnapshot.

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 401 ACCESS_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_LIMITED pode ser um bloqueio de cerca de 30 minutos, e KEEP_CALM também não é repetido;
  • outros 5xx;
  • erros de IA.
O 503 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 de Account.Snapshots.
  • 429 KEEP_CALM: chamadas demais a uma rota em pouco tempo.
O SDK nunca repete um 429. Diminua o ritmo e aguarde antes de tentar novamente.

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.