> ## 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. # Códigos de erro da API do Blob Storage > Todos os códigos de erro que a API do Blob Storage retorna, com status HTTP e o que fazer, e quando tentar de novo com backoff ou corrigir a requisição. Todo erro tem o mesmo formato. `code` é estável e feito para o seu código; `message`, quando presente, é uma explicação para humanos e pode mudar. ```json theme={"system"} { "status": "error", "code": "UPGRADE_REQUIRED", "message": "Custom metadata is available on Pro and Enterprise plans only." } ``` Tente novamente apenas em `429` e `5xx`, com backoff. Todo `4xx` que não seja `429` significa que a própria requisição precisa mudar. ## Autenticação e limites | Código | HTTP | Significado | | - | - | - | | `ACCESS_DENIED` | 401 | A credencial está ausente ou não foi reconhecida. | | `PERMISSION_DENIED` | 401 | A conta não tem um plano ativo, que esta ação exige. | | `MISSING_SCOPE` | 403 | A chave de API não tem o escopo de que esta rota precisa. Veja [Autenticação](/pt-br/blob-reference/authentication). | | `RESOURCE_NOT_ALLOWED` | 403 | A chave de API está restrita a aplicações específicas. | | `UPLOAD_TOKEN_NOT_ALLOWED` | 403 | Tokens de upload só funcionam nas rotas de upload. | | `UPLOAD_TOKEN_USED` | 401 | O token de upload não tem mais usos. Um token expirado responde `ACCESS_DENIED`. | | `ACCOUNT_BLOCKED` | 403 | A conta está bloqueada para armazenar arquivos. Entre em contato com o suporte. | | `UPGRADE_REQUIRED` | 403 | A opção não faz parte do seu plano. A `message` indica o plano que a libera. | | `RATE_LIMITED` | 429 | O limite próprio desta rota ou o orçamento de API da conta inteira foi atingido, ou o IP enviou credenciais inválidas demais. Aguarde e tente novamente. | ## Objetos | Código | HTTP | Significado | | - | - | - | | `INVALID_OBJECT` | 400 | O id do objeto está malformado ou não é seu. | | `INVALID_OBJECT_NAME` | 400 | `name` não corresponde ao padrão permitido (1 a 128 caracteres). | | `INVALID_OBJECT_PREFIX` | 400 | `prefix` não corresponde ao padrão permitido. | | `INVALID_OBJECT_EXPIRE` | 400 | `expire` não é uma duração válida (1 hora a 1825 dias). | | `INVALID_OBJECT_PRIVATE` | 400 | `private` não é `true` nem `false`. | | `INVALID_OBJECT_SECURITY_HASH` | 400 | `security_hash` não é um booleano, ou é `false` em um objeto privado. | | `INVALID_OBJECT_OVERWRITE` | 400 | `overwrite` não é `true` nem `false`. | | `INVALID_OBJECT_DISPOSITION` | 400 | `disposition` não é `inline` nem `attachment`. | | `INVALID_OBJECT_CACHE_CONTROL` | 400 | `cache_control` não é `immutable`, `no-cache` nem `max-age=60..31536000`. | | `INVALID_OBJECT_METADATA` | 400 | `metadata` está malformado, usa uma chave reservada ou passa de 5 chaves ou 512 bytes. | | `INVALID_STORAGE_AUTO_DOWNLOAD` | 400 | `auto_download` não é `true` nem `false`. | | `INVALID_CHECKSUM` | 400 | `checksum_sha256` não tem 64 caracteres hexadecimais minúsculos. | | `CHECKSUM_MISMATCH` | 400 | O arquivo não corresponde a `checksum_sha256`. Nada foi armazenado. | | `INVALID_DESTINATION` | 400 | O `destination` da cópia está malformado. | | `SAME_OBJECT` | 400 | A origem e o destino da cópia são o mesmo objeto. | | `NOTHING_TO_UPDATE` | 400 | A requisição não altera nenhum campo. | | `INVALID_CONTINUATION_TOKEN` | 400 | O `cursor` da listagem está malformado ou não é mais válido. Comece de novo sem cursor. | | `TOO_MANY_OBJECTS` | 400 | Objetos demais em uma requisição (100 para excluir, 50 para atualizar). | | `PREFIX_NOT_ALLOWED` | 403 | O token de upload está vinculado a outro prefixo. | | `OBJECT_NOT_FOUND` | 404 | O objeto não existe. | | `OBJECT_ALREADY_EXISTS` | 409 | Já existe um objeto com este id e `overwrite` é `false`. | | `OBJECT_IS_LEGACY` | por objeto | Retornado nos `results` da [Atualização de Objeto](/pt-br/blob-reference/endpoint/update). O objeto é um arquivo legado, armazenado antes da atualização de setembro de 2026, e precisa ser movido com a [Cópia de Objeto](/pt-br/blob-reference/endpoint/copy) (`move: true`) antes que os cabeçalhos dele possam mudar. | | `VISIBILITY_CHANGE_FAILED` | por objeto | Retornado nos `results` da [Atualização de Objeto](/pt-br/blob-reference/endpoint/update): o objeto não pôde ser tornado privado e **continua público**. Tente novamente. | | `UPDATE_FAILED` / `COPY_FAILED` / `DELETE_FAILED` | 500 | A operação falhou. Tente novamente. | ## Uploads | Código | HTTP | Significado | | - | - | - | | `INVALID_CONTENT_TYPE` | 409 | O [Envio de Objeto](/pt-br/blob-reference/endpoint/post) só aceita `multipart/form-data` com exatamente um arquivo. | | `INVALID_FILE` | 400 | A parte do arquivo está ausente ou ilegível. | | `INVALID_FILE_TYPE` | 400 | A extensão do arquivo está malformada ou é longa demais. | | `BLOCKED_FILE_TYPE` | 400 | Executáveis e instaladores não são aceitos. | | `FILE_TYPE_NOT_ALLOWED` | 400 | O token de upload ou a regra do prefixo não permite esta extensão. | | `FILE_TOO_SMALL` | 400 | Os arquivos precisam ter pelo menos 512 bytes. | | `FILE_TOO_LARGE` | 413 | Acima de 100 MB em uma requisição (use uploads em partes), ou acima do tamanho permitido pelo plano, token ou regra. | | `STORAGE_QUOTA_EXCEEDED` | 403 | A conta atingiu o armazenamento incluído. | | `TOO_MANY_CONCURRENT_UPLOADS` | 429 | Já há 4 uploads em andamento nesta conta. | | `PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE` | 503 | O armazenamento está temporariamente indisponível. Tente novamente. | | `UPLOAD_FAILED` | 500 | O upload falhou. Tente novamente. | ## Uploads em partes | Código | HTTP | Significado | | - | - | - | | `INVALID_UPLOAD_TOKEN` | 400 | O token `upload` está ausente, malformado ou não é seu. | | `INVALID_CHUNK_PART` | 400 | `part` não é um inteiro de 1 a 2048. | | `EMPTY_CHUNK` | 400 | O corpo da parte está vazio. | | `CHUNK_TOO_LARGE` | 413 | Uma parte tem mais de 32 MB. | | `CHUNK_TOO_SMALL` | 400 | Uma parte que não é a última tem menos de 5 MB. | | `NO_CHUNKS_UPLOADED` | 400 | A conclusão foi chamada antes de qualquer parte ser enviada. | | `TOO_MANY_OPEN_UPLOADS` | 429 | A conta tem 32 uploads abertos. Conclua ou cancele um. | | `TOO_MANY_CONCURRENT_CHUNKS` | 429 | Já há 6 partes em andamento nesta conta. | | `UPLOAD_NOT_FOUND` | 404 | O upload foi concluído, cancelado ou expirou. | ## Links temporários e compartilhamentos | Código | HTTP | Significado | | - | - | - | | `INVALID_DOWNLOAD_EXPIRES` | 400 | `expires` está fora do intervalo de 60 a 86400 segundos. | | `INVALID_FILENAME` | 400 | `filename` fica vazio depois de remover os caracteres inválidos. | | `INVALID_EXPIRES_IN` | 400 | `expires_in` está fora do intervalo permitido. | | `INVALID_MAX_DOWNLOADS` | 400 | `max_downloads` está fora do intervalo de 1 a 10000. | | `INVALID_PASSWORD` | 400 | A senha precisa ter de 8 a 128 caracteres. | | `INVALID_SHARE` | 400 | O id do compartilhamento está malformado. | | `SHARE_NOT_FOUND` | 404 | O compartilhamento não existe ou já foi revogado. | | `TOO_MANY_SHARES` | 409 | A conta tem 1000 compartilhamentos ativos. Revogue alguns primeiro. | ## Configurações da conta e tokens de upload | Código | HTTP | Significado | | - | - | - | | `INVALID_BODY` | 400 | O corpo está ausente ou não é um objeto JSON. | | `INVALID_RULES` | 400 | `rules` não é um array. | | `TOO_MANY_RULES` | 400 | Mais de 20 regras no Enterprise. Nos outros planos, passar do limite do plano (5 no Hobby e no Standard, 10 no Pro) responde `UPGRADE_REQUIRED`. | | `INVALID_RULE_PREFIX` / `DUPLICATE_RULE_PREFIX` | 400 | O prefixo de uma regra está malformado ou repete o de outra regra. | | `INVALID_RULE_PRIVATE` / `INVALID_RULE_EXPIRE` / `INVALID_RULE_MAX_SIZE` / `INVALID_RULE_EXTENSIONS` / `INVALID_RULE_CACHE_CONTROL` / `INVALID_RULE_DELETE_AFTER` | 400 | Um campo de uma regra é inválido. A resposta traz o `prefix` da regra. | | `INVALID_EXPIRES_IN` / `INVALID_MAX_USES` / `INVALID_MAX_SIZE` / `INVALID_ALLOWED_EXTENSIONS` | 400 | Um campo do token de upload está fora do intervalo. | | `UPLOAD_TOKEN_TOO_LARGE` | 400 | As opções não cabem em um token. Encurte os metadados ou a lista de extensões. | ## Credenciais S3 | Código | HTTP | Significado | | - | - | - | | `API_KEY_REQUIRED` | 400 | As credenciais S3 derivam de uma chave de API, não de uma sessão do dashboard. | | `LEGACY_API_KEY` | 400 | A chave de API usa o formato antigo. Crie uma nova chave nas configurações da sua conta. | | `INVALID_CREDENTIAL` | 401 | A chave de API não pôde ser verificada. | Já o [gateway S3](/pt-br/blob-reference/s3-compatibility) responde com os erros XML padrão do S3. ## Globais | Código | HTTP | Significado | | - | - | - | | `ROUTE_NOT_FOUND` / `NOT_FOUND` | 404 | A rota não existe. | | `INTERNAL_SERVER_ERROR` | 500 | Falha inesperada. Tente novamente mais tarde. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.