Saltar a contenido

Errores

Toda operación devuelve lo que promete o lanza un TaiStorageError, con lo que ha pasado y lo que hay que hacer:

from tai_storage import FileNotFoundError, TaiStorageError

try:
    origin.get_file("entrada/ventas.xlsx").read()
except FileNotFoundError as error:
    print(error)            # No existe el fichero 'entrada/ventas.xlsx' de … Solución: Comprueba la ruta y el nombre (con su extensión)
    error.message           # qué ha pasado
    error.solution          # qué hacer: siempre está
    error.details           # datos para diagnosticar (la ruta, lo que dijo el servicio); nunca secretos
    error.code              # ErrorCode.NOT_FOUND: estable, para decidir sin mirar el texto

Si un error no trae solución, o lo que sale es una traza de Python sin un TaiStorageError, es un fallo de la librería: repórtalo.

Las familias

Excepción code Cuándo
ConfigurationError CONFIGURATION Falta una credencial o una variable, o no es válida (un sitio que no existe, una biblioteca que no está)
AuthenticationError AUTHENTICATION El servicio rechaza las credenciales
PermissionDeniedError PERMISSION_DENIED Autenticado, pero sin permiso para esa operación
NotFoundError → FileNotFoundError, FolderNotFoundError NOT_FOUND No existe
AlreadyExistsError → FileAlreadyExistsError, FolderAlreadyExistsError ALREADY_EXISTS Ya existe y no se pidió overwrite=True
FolderNotEmptyError FOLDER_NOT_EMPTY Borrar una carpeta con contenido sin recursive=True
InvalidPathError INVALID_PATH La ruta sale del origen (..) o está mal formada
InvalidRequestError INVALID_REQUEST Un argumento que no vale, o el servicio rechaza la petición (un nombre no permitido, un patrón mal escrito)
ConflictError CONFLICT El servicio es ambiguo o está ocupado: dos ficheros con el mismo nombre en Drive, un fichero bloqueado, una copia que no coincide
StorageUnavailableError UNAVAILABLE Red, DNS, TLS, tiempo de espera, 5xx o 429 después de agotar los reintentos
OperationNotSupportedError NOT_SUPPORTED El backend no puede hacerlo (leer un documento nativo de Google)
DataError → DataFormatError, MissingColumnsError, ColumnTypeError INVALID_DATA Un fichero no se puede leer como tabla sin perder algo (ver DataFrames)

También son las de Python

Cuatro heredan además de la excepción equivalente de Python, así que un except de Python también las captura:

tai-storage Python
FileNotFoundError FileNotFoundError
FileAlreadyExistsError FileExistsError
PermissionDeniedError PermissionError
InvalidPathError ValueError
try:
    file.read()
except FileNotFoundError:     # el de Python: también captura el de tai-storage
    ...

En la 0.1 se llamaban igual que las de Python pero no heredaban de ellas, y un except FileNotFoundError sin importar el de tai-storage no las capturaba.

En un pipeline

from tai_storage import (
    AuthenticationError, ConfigurationError, FileNotFoundError, StorageUnavailableError, TaiStorageError,
)

try:
    procesar(origin)
except (ConfigurationError, AuthenticationError):
    raise                                  # no tiene sentido reintentar: hay que arreglar la configuración
except StorageUnavailableError:
    reprogramar_en_10_minutos()            # la librería ya ha reintentado lo razonable
except FileNotFoundError as error:
    avisar(f"No ha llegado el fichero del cliente: {error.message}")
except TaiStorageError as error:
    avisar(str(error))                     # mensaje + solución, listo para un aviso

Lo que la librería ya reintenta

Antes de lanzar StorageUnavailableError, SharePoint y Drive reintentan hasta 5 veces:

  • los 429 y los 5xx, con espera exponencial, o la que diga Retry-After;
  • los cortes de red, solo en las operaciones que se pueden repetir sin efectos (leer, listar);
  • el 403 por límite de peticiones de Drive.

Un 401 pide un token nuevo una vez. Si el token nuevo también es rechazado, es AuthenticationError. Cada reintento queda en el log en WARNING. Azure usa los reintentos de su SDK.

Los más habituales

ConfigurationError: Falta … Solución: Pásalo como argumento o define X=… en el entorno …

La variable X no está en el entorno del proceso. tai-storage no carga ficheros .env por su cuenta: si los usas, cárgalos antes de crear el origen.

FileAlreadyExistsError al subir

upload_file(), copy_to() y move_to() no sobrescriben sin overwrite=True. write() sí sobrescribe por defecto.

InvalidPathError: La ruta '…' sale del origen con '..'

Las rutas son relativas a la raíz del origen y no pueden subir por encima de ella. Para leer de otra raíz, crea otro origen.

ConflictError en Google Drive

Hay dos elementos con el mismo nombre en esa carpeta y la ruta es ambigua. Renombra uno, o léelo desde un list_files(), donde cada fichero lleva su id.

PermissionDeniedError: … storageQuotaExceeded

Una cuenta de servicio de Google no tiene cuota en «Mi unidad». La raíz tiene que estar en una unidad compartida: ver Google Drive.

Nombres de la 0.1

Siguen existiendo como alias, para no romper a quien los importa:

0.1 Es ahora
SecretNotFoundError ConfigurationError
OriginConnectionError StorageUnavailableError
OriginNotConnectedError ConfigurationError (las operaciones conectan solas)
PermissionError (de tai-storage) PermissionDeniedError