Errori

Ogni errore ha la stessa forma. code è stabile e pensato per il tuo codice; message, quando presente, è una spiegazione per le persone e può cambiare.

{
    "status": "error",
    "code": "UPGRADE_REQUIRED",
    "message": "Custom metadata is available on Pro and Enterprise plans only."
}

Riprova solo in caso di 429 e 5xx, con backoff. Ogni 4xx diverso da 429 significa che è la richiesta stessa a dover cambiare.

Autenticazione e limiti

Codice	HTTP	Significato
`ACCESS_DENIED`	401	La credenziale manca o non è stata riconosciuta.
`PERMISSION_DENIED`	401	L’account non ha un piano a pagamento attivo, necessario per questa azione.
`MISSING_SCOPE`	403	Alla chiave API manca lo scope richiesto da questa route. Vedi Autenticazione.
`RESOURCE_NOT_ALLOWED`	403	La chiave API è limitata ad applicazioni specifiche.
`UPLOAD_TOKEN_NOT_ALLOWED`	403	Gli upload token funzionano solo sulle route di upload.
`UPLOAD_TOKEN_USED`	401	L’upload token non ha più utilizzi disponibili. Un token scaduto risponde `ACCESS_DENIED`.
`ACCOUNT_BLOCKED`	403	L’account è bloccato e non può archiviare file. Contatta il supporto.
`UPGRADE_REQUIRED`	403	L’opzione non fa parte del tuo piano. Il `message` indica il piano che la sblocca.
`RATE_LIMIT`	429	Il budget API complessivo dell’account è esaurito, oppure l’IP ha inviato troppe credenziali non valide.
`RATE_LIMITED`	429	È stato raggiunto il limite specifico di questa route. Attendi e riprova.

Oggetti

Codice	HTTP	Significato
`INVALID_OBJECT`	400	L’id dell’oggetto è malformato o non ti appartiene.
`INVALID_OBJECT_NAME`	400	`name` non rispetta il pattern consentito (da 1 a 128 caratteri).
`INVALID_OBJECT_PREFIX`	400	`prefix` non rispetta il pattern consentito.
`INVALID_OBJECT_EXPIRE`	400	`expire` non è una durata valida (da 1 ora a 1825 giorni).
`INVALID_OBJECT_PRIVATE`	400	`private` non è `true` o `false`.
`INVALID_OBJECT_SECURITY_HASH`	400	`security_hash` non è un booleano, oppure è `false` su un oggetto privato.
`INVALID_OBJECT_OVERWRITE`	400	`overwrite` non è `true` o `false`.
`INVALID_OBJECT_DISPOSITION`	400	`disposition` non è `inline` o `attachment`.
`INVALID_OBJECT_CACHE_CONTROL`	400	`cache_control` non è `immutable`, `no-cache` o `max-age=60..31536000`.
`INVALID_OBJECT_METADATA`	400	`metadata` è malformato, usa una chiave riservata o supera 5 chiavi o 512 byte.
`INVALID_STORAGE_AUTO_DOWNLOAD`	400	`auto_download` non è `true` o `false`.
`INVALID_CHECKSUM`	400	`checksum_sha256` non è composto da 64 caratteri esadecimali minuscoli.
`CHECKSUM_MISMATCH`	400	Il file non corrisponde a `checksum_sha256`. Non è stato archiviato nulla.
`INVALID_DESTINATION`	400	La `destination` della copia è malformata.
`SAME_OBJECT`	400	L’origine e la destinazione della copia sono lo stesso oggetto.
`NOTHING_TO_UPDATE`	400	La richiesta non modifica alcun campo.
`INVALID_CONTINUATION_TOKEN`	400	Il `cursor` della lista è malformato o non è più valido. Ricomincia senza cursor.
`TOO_MANY_OBJECTS`	400	Troppi oggetti in una sola richiesta (100 per l’eliminazione, 50 per l’aggiornamento).
`PREFIX_NOT_ALLOWED`	403	L’upload token è vincolato a un altro prefisso.
`OBJECT_NOT_FOUND`	404	L’oggetto non esiste.
`OBJECT_ALREADY_EXISTS`	409	Esiste già un oggetto con questo id e `overwrite` è `false`.
`OBJECT_IS_LEGACY`	per oggetto	Restituito nei `results` di Object Update. L’oggetto è un file legacy, archiviato prima dell’aggiornamento di settembre 2026, e deve essere spostato con Object Copy (`move: true`) prima che i suoi header possano cambiare.
`VISIBILITY_CHANGE_FAILED`	per oggetto	Restituito nei `results` di Object Update: l’oggetto non ha potuto essere reso privato ed è ancora pubblico. Riprova.
`UPDATE_FAILED` / `COPY_FAILED` / `DELETE_FAILED`	500	L’operazione non è riuscita. Riprova.

Upload

Codice	HTTP	Significato
`INVALID_CONTENT_TYPE`	409	Object Post accetta solo `multipart/form-data` con esattamente un file.
`INVALID_FILE`	400	La parte del file manca o è illeggibile.
`INVALID_FILE_TYPE`	400	L’estensione del file è malformata o troppo lunga.
`BLOCKED_FILE_TYPE`	400	Eseguibili e installer non sono accettati.
`FILE_TYPE_NOT_ALLOWED`	400	L’upload token o la regola del prefisso non consente questa estensione.
`FILE_TOO_SMALL`	400	I file devono avere almeno 512 byte.
`FILE_TOO_LARGE`	413	Oltre 100 MB in una sola richiesta (usa gli upload chunked), oppure oltre la dimensione consentita dal piano, dal token o dalla regola.
`STORAGE_QUOTA_EXCEEDED`	403	L’account ha raggiunto lo storage incluso.
`TOO_MANY_CONCURRENT_UPLOADS`	429	Su questo account sono già in corso 4 upload.
`PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE`	503	Lo storage è temporaneamente non disponibile. Riprova.
`UPLOAD_FAILED`	500	L’upload non è riuscito. Riprova.

Upload chunked

Codice	HTTP	Significato
`INVALID_UPLOAD_TOKEN`	400	Il token `upload` manca, è malformato o non ti appartiene.
`INVALID_CHUNK_PART`	400	`part` non è un intero da 1 a 2048.
`EMPTY_CHUNK`	400	Il corpo della parte è vuoto.
`CHUNK_TOO_LARGE`	413	Una parte supera i 32 MB.
`CHUNK_TOO_SMALL`	400	Una parte diversa dall’ultima ha meno di 5 MB.
`NO_CHUNKS_UPLOADED`	400	Complete è stato chiamato prima dell’invio di qualsiasi parte.
`TOO_MANY_OPEN_UPLOADS`	429	L’account ha 32 upload aperti. Completane o annullane uno.
`TOO_MANY_CONCURRENT_CHUNKS`	429	Su questo account sono già in transito 6 parti.
`UPLOAD_NOT_FOUND`	404	L’upload è stato completato, annullato o è scaduto.

Link temporanei e condivisioni

Codice	HTTP	Significato
`INVALID_DOWNLOAD_EXPIRES`	400	`expires` è fuori dall’intervallo da 60 a 86400 secondi.
`INVALID_FILENAME`	400	`filename` è vuoto dopo la rimozione dei caratteri non validi.
`INVALID_EXPIRES_IN`	400	`expires_in` è fuori dall’intervallo consentito.
`INVALID_MAX_DOWNLOADS`	400	`max_downloads` è fuori dall’intervallo da 1 a 10000.
`INVALID_PASSWORD`	400	La password deve avere da 8 a 128 caratteri.
`INVALID_SHARE`	400	L’id della condivisione è malformato.
`SHARE_NOT_FOUND`	404	La condivisione non esiste o è già stata revocata.
`TOO_MANY_SHARES`	409	L’account ha 1000 condivisioni attive. Revocane alcune prima.

Impostazioni dell’account e upload token

Codice	HTTP	Significato
`INVALID_BODY`	400	Il corpo manca o non è un oggetto JSON.
`INVALID_RULES`	400	`rules` non è un array.
`TOO_MANY_RULES`	400	Più di 20 regole su Enterprise. Sugli altri piani, superare il limite del piano (5 su Hobby e Standard, 10 su Pro) risponde `UPGRADE_REQUIRED`.
`INVALID_RULE_PREFIX` / `DUPLICATE_RULE_PREFIX`	400	Il prefisso di una regola è malformato o ripete quello di un’altra regola.
`INVALID_RULE_PRIVATE` / `INVALID_RULE_EXPIRE` / `INVALID_RULE_MAX_SIZE` / `INVALID_RULE_EXTENSIONS` / `INVALID_RULE_CACHE_CONTROL` / `INVALID_RULE_DELETE_AFTER`	400	Un campo di una regola non è valido. La risposta riporta il `prefix` della regola.
`INVALID_EXPIRES_IN` / `INVALID_MAX_USES` / `INVALID_MAX_SIZE` / `INVALID_ALLOWED_EXTENSIONS`	400	Un campo dell’upload token è fuori intervallo.
`UPLOAD_TOKEN_TOO_LARGE`	400	Le opzioni non entrano in un token. Accorcia i metadati o l’elenco delle estensioni.

Credenziali S3

Codice	HTTP	Significato
`API_KEY_REQUIRED`	400	Le credenziali S3 derivano da una chiave API, non da una sessione della dashboard.
`LEGACY_API_KEY`	400	La chiave API usa il vecchio formato. Crea una nuova chiave nelle impostazioni del tuo account.
`INVALID_CREDENTIAL`	401	Non è stato possibile verificare la chiave API.

Il gateway S3 risponde invece con gli errori XML standard di S3.

Globali

Codice	HTTP	Significato
`ROUTE_NOT_FOUND` / `NOT_FOUND`	404	La route non esiste.
`INTERNAL_SERVER_ERROR`	500	Errore imprevisto. Riprova più tardi.

Primi Passi

Oggetti

Upload a Blocchi

Account

Link di Condivisione

S3

Autenticazione e limiti

Oggetti

Upload

Upload chunked

Link temporanei e condivisioni

Impostazioni dell’account e upload token

Credenziali S3

Globali

​Autenticazione e limiti

​Oggetti

​Upload

​Upload chunked

​Link temporanei e condivisioni

​Impostazioni dell’account e upload token

​Credenziali S3

​Globali

Autenticazione e limiti

Oggetti

Upload

Upload chunked

Link temporanei e condivisioni

Impostazioni dell’account e upload token

Credenziali S3

Globali