> ## Documentation Index > Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt > Use this file to discover all available pages before exploring further. # SDK JavaScript: erros e novas tentativas > Trate o SquareCloudAPIError no @squarecloud/api: status, código e mensagem, os códigos de erro próprios do SDK, novas tentativas, timeouts e rate limits. Toda falha da API, de rede ou local lança uma única classe: `SquareCloudAPIError`. Os exemplos usam o cliente `api` de [Criando o cliente](/pt-br/sdks/js/client#criando-o-cliente). `appId` é o id de uma das suas aplicações: [`api.account.me()`](/pt-br/sdks/js/client#conta) lista todas. ```typescript theme={"system"} 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//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](/pt-br/sdks/js/client#timeouts) | | 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 `. Um corpo 2xx que não é JSON tem a mensagem `Invalid JSON in HTTP 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**: ```typescript theme={"system"} 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](/pt-br/api-reference/errors) 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](/pt-br/sdks/js/client#chave-de-api-e-escopos)), 429 (veja [Rate limits](#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](/pt-br/sdks/js/ai#erros). ## 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](/pt-br/sdks/js/client#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](/pt-br/api-reference/limitations-and-restrictions)), 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 Todos os códigos de erro, com o significado e a solução. Os limites de requisições de cada plano. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.