Errores

Todos los errores tienen la misma forma. code es estable y está pensado para tu código; message, cuando aparece, es una explicación para personas y puede cambiar.

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

Reintenta solo ante 429 y 5xx, con backoff. Cualquier 4xx distinto de 429 significa que la propia solicitud tiene que cambiar.

Autenticación y límites

Código	HTTP	Significado
`ACCESS_DENIED`	401	La credencial falta o no se reconoció.
`PERMISSION_DENIED`	401	La cuenta no tiene un plan de pago activo, que esta acción requiere.
`MISSING_SCOPE`	403	La API key no tiene el scope que necesita esta ruta. Consulta Autenticación.
`RESOURCE_NOT_ALLOWED`	403	La API key está restringida a aplicaciones específicas.
`UPLOAD_TOKEN_NOT_ALLOWED`	403	Los tokens de subida solo funcionan en las rutas de subida.
`UPLOAD_TOKEN_USED`	401	Al token de subida no le quedan usos. Un token expirado responde `ACCESS_DENIED`.
`ACCOUNT_BLOCKED`	403	La cuenta tiene bloqueado el almacenamiento de archivos. Contacta con soporte.
`UPGRADE_REQUIRED`	403	La opción no forma parte de tu plan. El `message` indica el plan que la desbloquea.
`RATE_LIMIT`	429	Se agotó el presupuesto de API de toda la cuenta, o la IP envió demasiadas credenciales inválidas.
`RATE_LIMITED`	429	Se alcanzó el límite propio de esta ruta. Espera y reintenta.

Objetos

Código	HTTP	Significado
`INVALID_OBJECT`	400	El id del objeto está mal formado o no es tuyo.
`INVALID_OBJECT_NAME`	400	`name` no cumple el patrón permitido (de 1 a 128 caracteres).
`INVALID_OBJECT_PREFIX`	400	`prefix` no cumple el patrón permitido.
`INVALID_OBJECT_EXPIRE`	400	`expire` no es una duración válida (de 1 hora a 1825 días).
`INVALID_OBJECT_PRIVATE`	400	`private` no es `true` ni `false`.
`INVALID_OBJECT_SECURITY_HASH`	400	`security_hash` no es un booleano, o es `false` en un objeto privado.
`INVALID_OBJECT_OVERWRITE`	400	`overwrite` no es `true` ni `false`.
`INVALID_OBJECT_DISPOSITION`	400	`disposition` no es `inline` ni `attachment`.
`INVALID_OBJECT_CACHE_CONTROL`	400	`cache_control` no es `immutable`, `no-cache` ni `max-age=60..31536000`.
`INVALID_OBJECT_METADATA`	400	`metadata` está mal formado, usa una clave reservada o supera 5 claves o 512 bytes.
`INVALID_STORAGE_AUTO_DOWNLOAD`	400	`auto_download` no es `true` ni `false`.
`INVALID_CHECKSUM`	400	`checksum_sha256` no tiene 64 caracteres hexadecimales en minúsculas.
`CHECKSUM_MISMATCH`	400	El archivo no coincide con `checksum_sha256`. No se almacenó nada.
`INVALID_DESTINATION`	400	El `destination` de la copia está mal formado.
`SAME_OBJECT`	400	El origen y el destino de la copia son el mismo objeto.
`NOTHING_TO_UPDATE`	400	La solicitud no cambia ningún campo.
`INVALID_CONTINUATION_TOKEN`	400	El `cursor` de la lista está mal formado o ya no es válido. Vuelve a empezar sin cursor.
`TOO_MANY_OBJECTS`	400	Demasiados objetos en una solicitud (100 para eliminar, 50 para actualizar).
`PREFIX_NOT_ALLOWED`	403	El token de subida está vinculado a otro prefijo.
`OBJECT_NOT_FOUND`	404	El objeto no existe.
`OBJECT_ALREADY_EXISTS`	409	Ya existe un objeto con este id y `overwrite` es `false`.
`OBJECT_IS_LEGACY`	por objeto	Se devuelve en los `results` de Object Update. El objeto es un archivo heredado, almacenado antes de la actualización de septiembre de 2026, y debe moverse con Object Copy (`move: true`) antes de poder cambiar sus cabeceras.
`VISIBILITY_CHANGE_FAILED`	por objeto	Se devuelve en los `results` de Object Update: el objeto no se pudo hacer privado y sigue siendo público. Reintenta.
`UPDATE_FAILED` / `COPY_FAILED` / `DELETE_FAILED`	500	La operación falló. Reintenta.

Subidas

Código	HTTP	Significado
`INVALID_CONTENT_TYPE`	409	Object Post solo acepta `multipart/form-data` con exactamente un archivo.
`INVALID_FILE`	400	Falta la parte del archivo o no se puede leer.
`INVALID_FILE_TYPE`	400	La extensión del archivo está mal formada o es demasiado larga.
`BLOCKED_FILE_TYPE`	400	No se aceptan ejecutables ni instaladores.
`FILE_TYPE_NOT_ALLOWED`	400	El token de subida o la regla del prefijo no permiten esta extensión.
`FILE_TOO_SMALL`	400	Los archivos deben tener al menos 512 bytes.
`FILE_TOO_LARGE`	413	Supera 100 MB en una sola solicitud (usa subidas por partes), o supera el tamaño permitido por el plan, el token o la regla.
`STORAGE_QUOTA_EXCEEDED`	403	La cuenta alcanzó su almacenamiento incluido.
`TOO_MANY_CONCURRENT_UPLOADS`	429	Ya hay 4 subidas en curso en esta cuenta.
`PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE`	503	El almacenamiento no está disponible temporalmente. Reintenta.
`UPLOAD_FAILED`	500	La subida falló. Reintenta.

Subidas por partes

Código	HTTP	Significado
`INVALID_UPLOAD_TOKEN`	400	El token `upload` falta, está mal formado o no es tuyo.
`INVALID_CHUNK_PART`	400	`part` no es un entero de 1 a 2048.
`EMPTY_CHUNK`	400	El cuerpo de la parte está vacío.
`CHUNK_TOO_LARGE`	413	Una parte tiene más de 32 MB.
`CHUNK_TOO_SMALL`	400	Una parte que no es la última tiene menos de 5 MB.
`NO_CHUNKS_UPLOADED`	400	Se llamó a Complete antes de enviar ninguna parte.
`TOO_MANY_OPEN_UPLOADS`	429	La cuenta tiene 32 subidas abiertas. Completa o aborta una.
`TOO_MANY_CONCURRENT_CHUNKS`	429	Ya hay 6 partes en curso en esta cuenta.
`UPLOAD_NOT_FOUND`	404	La subida se completó, se abortó o expiró.

Enlaces temporales y enlaces compartidos

Código	HTTP	Significado
`INVALID_DOWNLOAD_EXPIRES`	400	`expires` está fuera del rango de 60 a 86400 segundos.
`INVALID_FILENAME`	400	`filename` queda vacío tras eliminar los caracteres no válidos.
`INVALID_EXPIRES_IN`	400	`expires_in` está fuera del rango permitido.
`INVALID_MAX_DOWNLOADS`	400	`max_downloads` está fuera del rango de 1 a 10000.
`INVALID_PASSWORD`	400	La contraseña debe tener de 8 a 128 caracteres.
`INVALID_SHARE`	400	El id del enlace compartido está mal formado.
`SHARE_NOT_FOUND`	404	El enlace compartido no existe o ya fue revocado.
`TOO_MANY_SHARES`	409	La cuenta tiene 1000 enlaces compartidos activos. Revoca algunos primero.

Configuración de la cuenta y tokens de subida

Código	HTTP	Significado
`INVALID_BODY`	400	El cuerpo falta o no es un objeto JSON.
`INVALID_RULES`	400	`rules` no es un array.
`TOO_MANY_RULES`	400	Más de 20 reglas en Enterprise. En los demás planes, superar el límite del plan (5 en Hobby y Standard, 10 en Pro) responde `UPGRADE_REQUIRED`.
`INVALID_RULE_PREFIX` / `DUPLICATE_RULE_PREFIX`	400	El prefijo de una regla está mal formado, o repite el de otra regla.
`INVALID_RULE_PRIVATE` / `INVALID_RULE_EXPIRE` / `INVALID_RULE_MAX_SIZE` / `INVALID_RULE_EXTENSIONS` / `INVALID_RULE_CACHE_CONTROL` / `INVALID_RULE_DELETE_AFTER`	400	Un campo de una regla no es válido. La respuesta incluye el `prefix` de la regla.
`INVALID_EXPIRES_IN` / `INVALID_MAX_USES` / `INVALID_MAX_SIZE` / `INVALID_ALLOWED_EXTENSIONS`	400	Un campo del token de subida está fuera de rango.
`UPLOAD_TOKEN_TOO_LARGE`	400	Las opciones del token no caben en un token. Acorta los metadatos o la lista de extensiones.

Credenciales S3

Código	HTTP	Significado
`API_KEY_REQUIRED`	400	Las credenciales S3 se derivan de una API key, no de una sesión del dashboard.
`LEGACY_API_KEY`	400	La API key usa el formato antiguo. Crea una key nueva en la configuración de tu cuenta.
`INVALID_CREDENTIAL`	401	No se pudo verificar la API key.

El gateway S3 responde en su lugar con errores XML estándar de S3.

Globales

Código	HTTP	Significado
`ROUTE_NOT_FOUND` / `NOT_FOUND`	404	La ruta no existe.
`INTERNAL_SERVER_ERROR`	500	Fallo inesperado. Reintenta más tarde.

Primeros Pasos

Objetos

Subida en Partes

Cuenta

Enlaces Compartidos

S3

Autenticación y límites

Objetos

Subidas

Subidas por partes

Enlaces temporales y enlaces compartidos

Configuración de la cuenta y tokens de subida

Credenciales S3

Globales

​Autenticación y límites

​Objetos

​Subidas

​Subidas por partes

​Enlaces temporales y enlaces compartidos

​Configuración de la cuenta y tokens de subida

​Credenciales S3

​Globales

Autenticación y límites

Objetos

Subidas

Subidas por partes

Enlaces temporales y enlaces compartidos

Configuración de la cuenta y tokens de subida

Credenciales S3

Globales