Erros

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.

{
    "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 pago 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.
`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_LIMIT`	429	O orçamento de API da conta inteira se esgotou, ou o IP enviou credenciais inválidas demais.
`RATE_LIMITED`	429	O limite próprio desta rota foi atingido. 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. O objeto é um arquivo legado, armazenado antes da atualização de setembro de 2026, e precisa ser movido com a Cópia de Objeto (`move: true`) antes que os cabeçalhos dele possam mudar.
`VISIBILITY_CHANGE_FAILED`	por objeto	Retornado nos `results` da Atualização de Objeto: 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 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 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.

Primeiros Passos

Objetos

Uploads em Partes

Conta

Links de Compartilhamento

S3

Autenticação e limites

Objetos

Uploads

Uploads em partes

Links temporários e compartilhamentos

Configurações da conta e tokens de upload

Credenciais S3

Globais

​Autenticação e limites

​Objetos

​Uploads

​Uploads em partes

​Links temporários e compartilhamentos

​Configurações da conta e tokens de upload

​Credenciais S3

​Globais

Autenticação e limites

Objetos

Uploads

Uploads em partes

Links temporários e compartilhamentos

Configurações da conta e tokens de upload

Credenciais S3

Globais