SDK JavaScript: erros e novas tentativas

Toda falha da API, de rede ou local lança uma única classe: SquareCloudAPIError. Os exemplos usam o cliente api de Criando o cliente. appId é o id de uma das suas aplicações: api.account.me() lista todas.

import { SquareCloudAPI, SquareCloudAPIError } from "@squarecloud/api";

try {
    await api.apps.start(appId);
} catch (error) {
    if (error instanceof SquareCloudAPIError) {
        console.error(error.status, error.code, error.message);
        console.error(error.method, error.path); // "POST" "/v2/apps/<id>/start"
    }
}

`SquareCloudAPIError`

SquareCloudAPIError estende Error (ele não é um TypeError).

Propriedade	Tipo	Descrição
`status`	`number`	Status HTTP. `0` quando nenhuma resposta chegou (erro de rede, timeout, verificação local)
`code`	`ErrorCode`	O código de erro da API, por exemplo `APP_NOT_FOUND`, ou um dos códigos do SDK
`message`	`string`	A explicação do servidor. Quando o servidor enviou apenas um código, o próprio código
`method`	`string`	Método HTTP da chamada que falhou
`path`	`string`	Caminho da URL da chamada que falhou, sem a query string
`cause`	`unknown`	O erro original, para `NETWORK_ERROR` e JSON inválido

Duas falhas não são encapsuladas:

Uma chamada abortada rejeita com o reason do signal. Um loop de realtime() abortado simplesmente termina.
Um caminho de upload que não pode ser aberto lança o erro do sistema de arquivos.

Códigos do SDK

Status	Código	Quando
0	`NETWORK_ERROR`	Sem resposta (DNS, conexão reiniciada, corpo cortado). O erro original está em `cause`
0	`TIMEOUT`	Sem resposta dentro do timeout
0	`FILE_TOO_LARGE`	Verificação local: um upload acima de 100 MB ou um `files.write` acima de 10 MB. Nada foi enviado
0	`INVALID_ID`	Verificação local: um id vazio, `.` ou `..`. Nada foi enviado
qualquer	`UNKNOWN_ERROR`	Uma resposta sem código (como uma página de erro de proxy), com o `status` real e a mensagem `HTTP <status>`. Um corpo 2xx que não é JSON tem a mensagem `Invalid JSON in HTTP <status> response`

O tipo `ErrorCode`

ErrorCode é apenas um tipo (sem objeto em runtime). Ele lista todos os códigos públicos da API, os depreciados e os do SDK, além de string & {}, então seu editor autocompleta os códigos conhecidos e novos códigos continuam passando na checagem de tipos. RATE_LIMIT e RATE_LIMIT_EXCEEDED continuam no tipo, marcados como depreciados: a API agora responde RATE_LIMITED para os dois. A lista de códigos da API cresce. Trate um código desconhecido pelo seu status HTTP:

async function start(appId: string) {
    try {
        await api.apps.start(appId);
    } catch (error) {
        if (!(error instanceof SquareCloudAPIError)) throw error;

        switch (error.code) {
            case "APP_NOT_FOUND":
                return null;
            case "CONTAINER_ALREADY_STARTED":
                return; // fine
            default:
                if (error.status === 429) return retryLater();
                if (error.status >= 500) return reportOutage(error);
                throw error;
        }
    }
}

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, …). Veja IA.

Novas tentativas

O SDK só tenta novamente o que é seguro repetir, até maxRetries vezes (padrão 2, ou seja, até 3 tentativas):

Repetido	Métodos
`NETWORK_ERROR`	Apenas `GET`
503 `UPLOAD_BUSY`	Qualquer método
503 `ANALYTICS_BUSY`	Qualquer método
503 `DATABASE_UNAVAILABLE`	Apenas `GET`

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. 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 maxRetries: 0 para desativar as novas tentativas.

Timeouts

timeoutMs (30 s) se aplica por tentativa e cobre a resposta inteira. Veja Timeouts para as chamadas com mínimo de 120 s e as chamadas sem timeout. Um timeout lança TIMEOUT com status 0 e nunca é repetido.

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.

CLI

VS Code

SDKs

SDK JavaScript: erros e novas tentativas

`SquareCloudAPIError`

Códigos do SDK

O tipo `ErrorCode`

Códigos de erro da API

Novas tentativas

Timeouts

Rate limits

Próximos passos

Referência de erros da API

Limitações e restrições

​SquareCloudAPIError

​Códigos do SDK

​O tipo ErrorCode

​Códigos de erro da API

​Novas tentativas

​Timeouts

​Rate limits

​Próximos passos

Referência de erros da API

Limitações e restrições

`SquareCloudAPIError`

Códigos do SDK

O tipo `ErrorCode`

Códigos de erro da API

Novas tentativas

Timeouts

Rate limits

Próximos passos