Códigos de erro da API e como resolver

Toda requisição com falha à API da Square Cloud responde com um status HTTP e um corpo JSON que traz um code legível por máquina. Esta página lista todos os códigos, agrupados por área. A página de cada endpoint também lista os códigos que aquele endpoint retorna com mais frequência.

O Blob Storage tem a sua própria lista de códigos, e o AI Gateway responde no formato de erro da OpenAI, com códigos em minúsculas. Nenhum dos dois é coberto aqui.

Formato do erro

{
  "status": "error",
  "code": "APP_NOT_FOUND",
  "message": "Optional explanation for humans."
}

Campo	Descrição
`status`	Sempre `"error"` em uma falha.
`code`	O código do erro, em `UPPER_SNAKE_CASE`. Use este campo para decidir o que fazer.
`message`	Opcional. Uma explicação legível por pessoas que pode mudar a qualquer momento: mostre para as pessoas, mas nunca faça parse dela.

A lista de códigos cresce com o tempo. Trate um código que você não conhece como uma falha genérica do status HTTP que veio com ele: corrija a requisição em um 4xx, espere em um 429 e tente de novo mais tarde em um 5xx.

Novas tentativas

A API não envia o header Retry-After, então a decisão é sua. Uma política segura:

Resposta	O que fazer
`400`, `401`, `403`, `404`, `409`, `413`, `415`	Não repita a mesma requisição: ela falha do mesmo jeito. Corrija antes a entrada, a credencial ou o plano.
`429`	Espere antes da próxima requisição. Repetir em loop mantém você bloqueado. Veja Limites de requisições.
`503 UPLOAD_BUSY`, `503 ANALYTICS_BUSY`	Tente de novo após uma pausa curta, com backoff exponencial.
`503 DATABASE_UNAVAILABLE`	Repita uma leitura depois de alguns segundos. Uma escrita pode já ter sido aplicada, então confira o recurso antes de repeti-la.
`500` e outros `5xx`	Tente de novo uma ou duas vezes com backoff. Se continuar falhando, confira o status do serviço.

202 SNAPSHOT_PROCESSING mantém o envelope de erro por compatibilidade, mas não é uma falha: o snapshot ainda está sendo gerado e aparece na listagem sozinho. Não peça de novo.

Limites de requisições

Dois códigos respondem 429, e eles significam coisas diferentes:

RATE_LIMITED: o orçamento de requisições da sua conta ou chave de API, contado a cada 60 segundos e definido pelo seu plano (veja os valores por plano). Acima dele, a API recusa as suas requisições por até 30 minutos. Alguns endpoints também respondem RATE_LIMITED para os seus próprios limites, e um endereço IP que insiste em enviar chaves de API que não pertencem a nenhuma conta fica bloqueado por um curto período.
KEEP_CALM: o limite próprio de um endpoint, como uma reinicialização a cada poucos segundos. Espere um momento e tente de novo. O limite de cada endpoint está na página dele.

Autenticação e permissões

Código	HTTP	Significado e solução
`ACCESS_DENIED`	401	A chave de API está ausente, foi digitada errado, foi revogada ou expirou, ou a conta dela não existe mais. Confira a chave nas configurações de segurança da sua conta e não repita em loop.
`MISSING_SCOPE`	403	A chave é válida, mas não tem o escopo que este endpoint exige. Escopos não podem ser editados, então crie uma chave com esse escopo. Veja Escopos.
`RESOURCE_NOT_ALLOWED`	403	A chave está restrita a aplicações e bancos de dados que não incluem este, ou o endpoint vale para a conta inteira e a chave é restrita. Use uma chave que cubra o recurso.
`PERMISSION_DENIED`	403	A sua função no workspace não permite esta ação em uma aplicação compartilhada, como ler o `.env` sem a função `admin`. Veja as funções do workspace.
`SCOPE_NOT_GRANTABLE`	403	Uma chave de API restrita tentou conceder mais acesso do que tem, por exemplo adicionar um membro `admin` com uma chave sem `envs:write`. Use uma chave que tenha todos os escopos dessa função, ou o dashboard.
`UPGRADE_REQUIRED`	402 / 403	O recurso exige um plano maior: bancos de dados, domínios personalizados e workspaces exigem o Standard ou acima, logs e performance de rede exigem o Pro ou acima, e listar os snapshots da conta exige um plano ativo (`402`). A `message` informa o plano quando possível.

Validação da requisição

Código	HTTP	Significado e solução
`INVALID_JSON_BODY`	400	O corpo não é um JSON válido. Envie `Content-Type: application/json` e um corpo bem formado.
`INVALID_INPUT`	400	Um campo falhou na validação. A `message` diz qual.
`INVALID_ID`	400	Um id obrigatório, geralmente `workspaceId`, está ausente ou malformado.
`INVALID_CONTENT_TYPE`	415	Upload e commit exigem `multipart/form-data` com o zip em um campo `file`.
`PAYLOAD_TOO_LARGE`	413	O corpo é maior do que este endpoint aceita.
`ROUTE_NOT_FOUND`	404	O caminho ou o método HTTP está errado. Compare com a página do endpoint.

Cotas e limites de conexão

Código	HTTP	Significado e solução
`RATE_LIMITED`	429	O orçamento de requisições da sua conta ou chave foi atingido, ou o limite próprio de um endpoint. Veja Limites de requisições.
`KEEP_CALM`	429	Requisições demais a este endpoint em pouco tempo. Espere um momento e tente de novo.
`DAILY_SNAPSHOTS_LIMIT_REACHED`	429	A cota de snapshots manuais do plano nas últimas 24 horas acabou. Espere antes do próximo, ou faça upgrade para uma cota maior.
`REALTIME_MAX_CONNECTIONS`	429	A sua conta já tem 5 conexões de tempo real abertas. Feche uma antes.
`REALTIME_MAX_CONNECTIONS_APP`	429	A aplicação já tem 30 conexões de tempo real abertas, somando todos os usuários.

Aplicações

Código	HTTP	Significado e solução
`APP_NOT_FOUND`	404	A aplicação não existe, não é sua, ou você não é membro do workspace em que ela está compartilhada. Confira o id. As rotas de workspace respondem `400` quando falta o `appId` no corpo.
`CONTAINER_ALREADY_STARTED`	409	A aplicação ou o banco de dados já está em execução. Você pode tratar como sucesso.
`CONTAINER_ALREADY_STOPPED`	409	A aplicação ou o banco de dados já está parado. Você pode tratar como sucesso.
`CONTAINER_TEMPORARILY_SUSPENDED`	409	O recurso está suspenso. Confira o e-mail da conta para saber o motivo.
`CONTAINER_NOT_FOUND`	409	O container do recurso não foi encontrado no servidor dele. Tente de novo em instantes e fale com o suporte se persistir.
`CONTAINER_INSUFFICIENT_DISK_SPACE`	409	Não há espaço em disco suficiente para iniciar. Remova arquivos de que você não precisa e tente de novo.
`CONTAINER_NETWORK_CONFLICT`	409	Um conflito de rede ou de porta impediu o início. Tente de novo em instantes.
`ACTION_FAILED`	409	O início, a parada ou a reinicialização foi recusado por outro motivo, por exemplo durante um deploy. Confira o status e tente de novo.
`RESTORE_IN_PROGRESS`	403	Uma restauração de snapshot está em andamento neste recurso. Espere terminar antes de excluir a aplicação, ou de iniciar, parar ou excluir o banco de dados.
`DELETE_FAILED`	404	O servidor que hospeda o recurso recusou a exclusão. Tente de novo. No gerenciador de arquivos, o mesmo código responde `400`.
`LOGS_UNAVAILABLE`	404	Não foi possível ler os logs: a aplicação está offline, nunca recebeu um deploy, ou o servidor não respondeu. Tente de novo em instantes.
`METRICS_NOT_SUPPORTED`	400	As métricas só são coletadas para aplicações com pelo menos 512 MB de RAM.

Upload e commit

Código	HTTP	Significado e solução
`INVALID_FILE`	400	O formulário não tem arquivo no campo `file`.
`INVALID_FILENAME`	400	O nome do arquivo tem separadores de caminho, `..` ou caracteres de controle.
`INVALID_PATH`	400	O `path` de um commit contém traversal ou caracteres de shell.
`FILE_TOO_LARGE`	413	O zip passa de 100 MB.
`UPLOAD_ABORTED`	400	A conexão fechou antes de o upload terminar. Envie de novo.
`UPLOAD_BUSY`	503	Há uploads demais em andamento na plataforma. Tente de novo após uma pausa curta.
`STORAGE_UPLOAD_FAILED`	400	Não foi possível armazenar o zip. Tente de novo mais tarde.
`UPLOAD_FAILED`	400	Não foi possível processar o upload. Tente de novo e confira o zip se acontecer outra vez.
`COMMIT_FAILED`	400	Não foi possível aplicar o commit. Tente de novo e confira o zip se acontecer outra vez.
`INSUFFICIENT_MEMORY`	400	O seu plano não tem memória livre suficiente para a aplicação ou o banco de dados, ou o `MEMORY` está abaixo do mínimo: 256 MB, ou 512 MB para um site com `SUBDOMAIN`. Ajuste o `MEMORY`, exclua algo ou faça upgrade.
`CLUSTER_SELECTION_FAILED`	400	Nenhum servidor tinha espaço para a nova aplicação ou o novo banco de dados agora. Tente de novo mais tarde.
`CLUSTER_MAINTENANCE_TRY_LATER`	503	Novas aplicações e bancos de dados estão pausados por manutenção. Tente de novo mais tarde.
`EMPTY_RESPONSE`	400	O servidor que recebeu o upload não deu uma resposta utilizável, então a aplicação não foi criada. Envie de novo.

Verificações do zip e da configuração

Quando você faz o upload de uma aplicação, o servidor que vai executá-la verifica o zip e o arquivo de configuração (squarecloud.app ou squarecloud.config). Uma verificação com falha responde 400 com um destes códigos, e nenhum deploy é feito. Corrija o zip e envie de novo. Um commit não lê o arquivo de configuração: ele só pode falhar com FAILED_EXTRACT ou CONTAINER_INSUFFICIENT_DISK_SPACE desta lista.

Código	HTTP	Significado e solução
`FAILED_EXTRACT`	400	Não foi possível extrair o zip. Crie de novo com uma ferramenta de zip padrão e confira se ele não está corrompido.
`DOWNLOAD_FAILED`	400	O servidor não conseguiu buscar o zip depois de recebê-lo. Envie de novo.
`MISSING_CONFIG`	400	O zip não tem `squarecloud.app` nem `squarecloud.config` na raiz, ou o arquivo está vazio.
`MISSING_MEMORY`, `MISSING_DISPLAY_NAME`, `MISSING_VERSION`	400	Um campo obrigatório do arquivo de configuração está ausente ou vazio. O código informa o primeiro que falta.
`MISSING_MAIN`	400	A configuração não tem `MAIN` nem `RUNTIME`. Defina um dos dois.
`INVALID_MAIN`	400	O `MAIN` tem caracteres além de letras, dígitos, `_`, `.`, `/` e `-`, ou mais de 32 caracteres. Sem `RUNTIME`, ele também falha quando o arquivo não está no zip, está vazio, aponta para fora do projeto, ou não tem extensão ou tem uma que não corresponde a nenhuma linguagem suportada.
`INVALID_RUNTIME`	400	O `RUNTIME` não é um dos valores suportados listados na referência do arquivo de configuração.
`INVALID_VERSION`	400	O `VERSION` precisa ser `recommended` ou `latest`. Um número de versão exato é recusado.
`INVALID_START`	400	O `START` passa de 256 caracteres.
`INVALID_DEPENDENCY`	400	O arquivo de dependências da linguagem está ausente ou vazio: `package.json` para JavaScript e TypeScript, `requirements.txt` ou `pyproject.toml` para Python, `go.mod` ou `go.work` para Go, `Cargo.toml` para Rust, `Gemfile` para Ruby, `mix.exs` para Elixir.
`INVALID_DISPLAY_NAME`	400	O `DISPLAY_NAME` precisa ter de 1 a 32 caracteres: letras, dígitos, espaços, `_` e `-`.
`INVALID_DESCRIPTION`	400	O `DESCRIPTION` passa de 280 caracteres.
`INVALID_SUBDOMAIN`	400	O `SUBDOMAIN` está malformado, é reservado ou já está em uso. Escolha outro.
`CONTAINER_INSUFFICIENT_DISK_SPACE`	400	Em um commit, não há espaço em disco suficiente para os novos arquivos. Exclua arquivos de que você não precisa e faça o commit de novo.
`ACCESS_FORBIDDEN`	400	O servidor não conseguiu carregar a sua conta para este upload. Tente de novo e fale com o suporte se persistir.

Variáveis de ambiente

Código	HTTP	Significado e solução
`STATIC_APP_ENV_NOT_SUPPORTED`	400	Sites estáticos não suportam variáveis de ambiente.
`INVALID_ENV_CONTENT`	400	`envs` está ausente ou tem o formato errado: um objeto para adicionar ou substituir, um array de chaves para remover.
`TOO_MANY_ENV_VARS`	400	A aplicação ficaria com mais de 256 variáveis.
`ENV_NAME_TOO_LONG`	400	Uma chave passa de 1024 caracteres, ou não é uma string.
`ENV_CONTENT_TOO_LONG`	400	Um valor passa de 4096 caracteres.
`READ_FAILED`	400	Não foi possível ler as variáveis da aplicação. Tente de novo. A rota do certificado usa o mesmo código.

Arquivos

Código	HTTP	Significado e solução
`INVALID_PATH`	400	O caminho tem traversal ou caracteres inválidos, passa de 256 caracteres, ou a origem e o destino de uma movimentação são iguais.
`BLOCKED_PATH`	403	O caminho está em um diretório protegido, ou a sua função no workspace não pode gravar esse arquivo.
`INVALID_ENCODING`	400	`encoding` aceita apenas `base64`.
`INVALID_CONTENT`	400	`content` está ausente, tem um formato não suportado ou não é um base64 válido.
`FILE_NOT_FOUND`	404	Não há arquivo nem diretório nesse caminho.
`FILE_TOO_LARGE`	413	O gerenciador de arquivos lê e grava arquivos de até 10 MB. Use o commit para arquivos maiores.
`RENAME_FAILED`	400	Não foi possível mover ou renomear o arquivo. Tente de novo.
`DELETE_FAILED`	400	Não foi possível excluir o arquivo. Tente de novo.
`INVALID_DISPLAY_NAME`, `INVALID_DESCRIPTION`, `INVALID_MEMORY`, `INVALID_AUTORESTART`, `INVALID_SUBDOMAIN`	400	Uma escrita no arquivo de configuração tem um campo que falha na validação, ou um `SUBDOMAIN` que já está em uso. Corrija esse campo.
`CANNOT_SET_SUBDOMAIN`	400	A configuração de um site não tem `SUBDOMAIN`. Um site sempre mantém um, então defina-o de volta.
`SAVE_FAILED`	500	Não foi possível salvar a nova configuração. Tente de novo.

Deploys e GitHub

Código	HTTP	Significado e solução
`INVALID_ACCESS_TOKEN`	400	O token do webhook não é um token do GitHub (`ghp_...`, `github_pat_...`) nem `@`.
`MISSING_REQUIRED_FIELDS`	400	`repositoryName` ou `repositoryBranch` está ausente.
`INVALID_BRANCH_LENGTH`	400	O nome da branch passa de 256 caracteres.
`BRANCH_NOT_FOUND`	400	A branch não existe no repositório.
`GIT_ALREADY_CONFIGURED`	400	A aplicação já tem um repositório vinculado. Desvincule antes.
`GIT_NOT_CONFIGURED`	400	A aplicação não tem repositório vinculado para desvincular.
`GITHUB_NOT_CONNECTED`	403	A sua conta da Square Cloud não tem uma conexão com o GitHub funcionando. Conecte ou reconecte o GitHub no dashboard.
`REPOSITORY_NOT_AVAILABLE`	403	O GitHub App da Square Cloud não está instalado no repositório pela sua conta do GitHub.
`REPOSITORY_PERMISSION_REQUIRED`	403	A sua conta do GitHub precisa de acesso de escrita ao repositório.
`REPOSITORY_NOT_FOUND`	404	O repositório não existe ou a sua conta do GitHub não consegue vê-lo.
`REPOSITORY_BRANCH_ALREADY_CONFIGURED`	409	Outra aplicação, de qualquer conta, já usa este repositório e esta branch.
`FAILED_TO_FETCH`	502	O GitHub não confirmou a branch. Tente de novo.
`VALIDATION_FAILED`	500 / 502	Não foi possível validar o repositório. Tente de novo.
`VALIDATION_TIMEOUT`	504	A validação do repositório demorou demais. Tente de novo.

Um deploy via Git que falha não é um erro HTTP: ele aparece no histórico de deploys como um evento com state: "error" e um code como DEPLOY_FAILED.

Rede e domínios

Código	HTTP	Significado e solução
`INVALID_TIME_RANGE`	400	`start` ou `end` está ausente ou malformado, ou `start` vem depois de `end`.
`INVALID_FILTER`	400	Um filtro do endpoint de análise tem o formato errado.
`UNABLE_TO_FETCH_ANALYTICS`, `UNABLE_TO_FETCH_ERRORS`, `UNABLE_TO_FETCH_PERFORMANCE`	500	O provedor de edge não retornou os dados. Tente de novo mais tarde.
`ANALYTICS_BUSY`	503	A análise de rede está ocupada em toda a plataforma. Tente de novo após uma pausa curta.
`NO_CUSTOM_DOMAIN`	400	A aplicação não tem domínio personalizado, então não há registros DNS para mostrar.
`INVALID_DOMAIN`	400	O valor não é um nome de domínio válido.
`RESERVED_DOMAIN`	400	Os domínios da própria Square Cloud e os subdomínios deles não podem ser usados como domínio personalizado.
`DOMAIN_ALREADY_EXISTS`	409	Outra conta já usa este domínio. Remova-o de lá antes.
`LOAD_BALANCER_LIMIT_REACHED`	403	O seu plano não permite este domínio em mais aplicações. A `message` informa o limite.
`DNS_FAILED`	502	O provedor de edge não conseguiu associar o domínio. O seu domínio anterior continua no lugar. Tente de novo.
`PURGE_CACHE_FAILED`	500	A limpeza de cache não terminou. Tente de novo em instantes.

Snapshots

Código	HTTP	Significado e solução
`SNAPSHOT_PROCESSING`	202	Não é um erro: o snapshot ainda está sendo gerado. Confira a listagem em alguns minutos.
`SNAPSHOT_FAILED`	404	Não foi possível criar o snapshot. Tente de novo mais tarde.
`MISSING_PARAMETERS`	400	`snapshotId` ou `versionId` está ausente.
`INVALID_SNAPSHOT_ID`	400	`snapshotId` não é um `name` da listagem de snapshots.
`INVALID_VERSION_ID`	400	`versionId` não é um `version_id` da listagem de snapshots.
`SNAPSHOT_NOT_FOUND`	404	Nenhum snapshot corresponde a esse id e a essa versão.
`SNAPSHOT_RESTORE_FAILED`	404	A restauração falhou. Tente de novo, ou restaure outro snapshot.
`SNAPSHOT_DATABASE_MISMATCH`	400	O snapshot é de um motor de banco de dados diferente do banco de destino.
`INVALID_SCOPE`	400	O `scope` da listagem de snapshots da conta precisa ser `applications` ou `databases`.

Bancos de dados

Código	HTTP	Significado e solução
`DATABASE_NOT_FOUND`	404	O banco de dados não existe ou não é seu.
`INVALID_NAME`	400	O nome precisa ter de 1 a 32 caracteres. Workspaces seguem a mesma regra.
`INVALID_DATABASE_TYPE`	400	`type` precisa ser `mongo`, `mysql`, `postgres` ou `redis`.
`INVALID_DATABASE_VERSION`	400	A versão não está disponível para esse motor.
`INVALID_MEMORY`	400	A memória não é válida para este motor ou plano.
`DATABASE_CREATION_FAILED`	400 / 500	Não foi possível criar o banco de dados. Nada ficou para trás, então você pode tentar de novo.
`DATABASE_NOT_RUNNING`	400	Inicie o banco de dados antes de ler o certificado dele ou redefinir as credenciais.
`INVALID_RESET_TYPE`	400	`reset` precisa ser `password` ou `certificate`.
`RESET_FAILED`	500	Não foi possível redefinir as credenciais. Tente de novo.
`NO_UPDATE_DATA`	400	Envie `name`, `ram` ou os dois para atualizar um banco de dados.

Workspaces

Código	HTTP	Significado e solução
`WORKSPACE_NOT_FOUND`	404	O workspace não existe, ou você não é o dono nem um membro dele.
`WORKSPACE_LIMIT_REACHED`	400	A sua conta já tem o máximo de workspaces que o plano permite.
`WORKSPACE_CREATION_FAILED`	400	Não foi possível criar o workspace. Tente de novo.
`INVALID_CODE`	400	O código de convite está ausente, malformado ou expirou. Peça um novo à pessoa.
`INVALID_GROUP`	400	`group` precisa ser `view`, `manager`, `maintain` ou `admin`.
`CANNOT_INVITE_OWNER`	400	O código de convite é seu, e você já é o dono do workspace.
`CANNOT_EDIT_OWNER`	400	A função do dono não pode ser alterada.
`CANNOT_LEAVE_OWNER`	400	O dono não pode sair do workspace. Exclua o workspace em vez disso.
`MEMBERS_LIMIT_REACHED`	400	O workspace já tem o máximo de membros que o plano do dono permite.
`MEMBER_ALREADY_ADDED`	400	Essa pessoa já é membro.
`MEMBER_NOT_FOUND`	400 / 404	`memberId` está ausente (`400`) ou essa pessoa não é mais membro (`404`).
`APPLICATIONS_LIMIT_REACHED`	400	O workspace já compartilha 100 aplicações.
`APP_ALREADY_IN_WORKSPACE`	400	A aplicação já está compartilhada neste workspace.

Plataforma

Código	HTTP	Significado e solução
`INTERNAL_SERVER_ERROR`	500	Uma falha inesperada. Tente de novo uma vez e fale com o suporte se persistir.
`DATABASE_UNAVAILABLE`	503	O banco de dados da plataforma está indisponível por um instante. Tente de novo em alguns segundos. Um recurso existente nunca é reportado como não encontrado nesse estado.
`CLUSTER_TIMEOUT`	400	O servidor que hospeda o recurso não respondeu a tempo. Tente de novo.
`CLUSTER_UNAVAILABLE`	400	O servidor que hospeda o recurso não pode ser alcançado agora. Tente de novo em instantes.
`REQUEST_ABORTED`	400	A requisição foi cancelada antes de o servidor que hospeda o recurso responder. Tente de novo.
`INVALID_PARAMETERS`	400	Uma requisição interna estava malformada. Tente de novo e fale com o suporte se persistir.

Os códigos AI_* (AI_DAILY_LIMIT_REACHED, AI_NO_PLAN_LIMIT_REACHED, AI_MAX_CONCURRENT_STREAMS, AI_UNAVAILABLE) pertencem ao assistente de IA do dashboard, que exige uma sessão do dashboard. Uma chave de API nunca os recebe.

Relacionados

Autenticação e escopos
Limites de requisições por plano
SDK de JavaScript: SquareCloudAPIError
SDK de Python: SquareCloudAPIError
SDK de Go: *APIError

Primeiros passos

Conta

Aplicações

Bancos de dados

Workspaces

IA

Códigos de erro da API e como resolver

Formato do erro

Novas tentativas

Limites de requisições

Autenticação e permissões

Validação da requisição

Cotas e limites de conexão

Aplicações

Upload e commit

Verificações do zip e da configuração

Variáveis de ambiente

Arquivos

Deploys e GitHub

Rede e domínios

Snapshots

Bancos de dados

Workspaces

Plataforma

Relacionados

​Formato do erro

​Novas tentativas

​Limites de requisições

​Autenticação e permissões

​Validação da requisição

​Cotas e limites de conexão

​Aplicações

​Upload e commit

​Verificações do zip e da configuração

​Variáveis de ambiente

​Arquivos

​Deploys e GitHub

​Rede e domínios

​Snapshots

​Bancos de dados

​Workspaces

​Plataforma

​Relacionados

Formato do erro

Novas tentativas

Limites de requisições

Autenticação e permissões

Validação da requisição

Cotas e limites de conexão

Aplicações

Upload e commit

Verificações do zip e da configuração

Variáveis de ambiente

Arquivos

Deploys e GitHub

Rede e domínios

Snapshots

Bancos de dados

Workspaces

Plataforma

Relacionados