Skip to main content
A v6 é uma reescrita: um cliente plano, dados simples em vez de classes, ids como primeiro argumento e uma única classe de erro. A maioria das mudanças é mecânica.

Visão geral

Construção e opções

Método a método

Tipos

Os tipos vêm com o SDK e espelham os nomes de campos da API. As principais renomeações em relação ao @squarecloud/api-types e às classes da v5:

Erros

  • Os códigos sintéticos foram removidos (RATE_LIMIT_EXCEEDED, PAYLOAD_TOO_LARGE, SERVER_UNAVAILABLE, UNKNOWN_ERROR_<status>): o código real da API aparece (RATE_LIMITED, KEEP_CALM, DAILY_SNAPSHOTS_LIMIT_REACHED, FILE_TOO_LARGE…).
  • Sem resposta: status: 0 com NETWORK_ERROR (a causa em cause) ou TIMEOUT. Um corpo sem código resulta em UNKNOWN_ERROR com o status real e a mensagem HTTP <status>.
  • instanceof TypeError não é mais verdadeiro para erros da API.
  • Uma chave expirada resulta em 401 ACCESS_DENIED, assim como uma desconhecida.
  • Os erros de ai.chat(), incluindo os de autenticação e rate limit, trazem o código da OpenAI em minúsculas (access_denied, rate_limit_exceeded, …).
  • Um start/stop/restart recusado resulta em 409 apenas com um código: CONTAINER_ALREADY_STARTED, CONTAINER_ALREADY_STOPPED, CONTAINER_TEMPORARILY_SUSPENDED, CONTAINER_NOT_FOUND, CONTAINER_INSUFFICIENT_DISK_SPACE, CONTAINER_NETWORK_CONFLICT ou ACTION_FAILED.

Mudanças de comportamento

  • As chamadas expiram: 30 s por tentativa por padrão (a v5 não tinha timeout), pelo menos 120 s para chamadas que o servidor mantém abertas. Defina timeoutMs: 0 para nenhum.
  • files.write() trata uma string como o conteúdo e a envia como texto simples; bytes vão como base64, seguros para binários, e conteúdo vazio cria um arquivo vazio (mesmo formato de envio dos SDKs Python e Go). files.read() solicita base64 e o decodifica.
  • files.list() de um diretório inexistente lança 404 FILE_NOT_FOUND em vez de retornar [].
  • snapshots.create() retorna { pending: true } em um 202 em vez de lançar erro.
  • Resultados string nunca são undefined: setWebhook e resetCredentials("certificate") retornam "" quando a API não envia nada; deploys.current() retorna {}.
  • realtime() se reconecta em conexões perdidas e em REALTIME_RECONNECT (até 3 vezes seguidas, no máximo uma abertura a cada 5,5 s).
  • Novas tentativas: erros de rede em GET e 503 UPLOAD_BUSY/ANALYTICS_BUSY (além de DATABASE_UNAVAILABLE em GET), com backoff. 429 nunca é repetido. DATABASE_UNAVAILABLE pode chegar depois que uma mutação foi aplicada: repita você mesmo suas mutações idempotentes.
  • Ids vazios, . e .. falham localmente com INVALID_ID.
  • Valores de query que são undefined, "" ou false não são enviados.