Skip to main content

SquareCloudBlobError

Todo fallo de la API lanza un SquareCloudBlobError.

Lo que no es un SquareCloudBlobError

  • Los errores de red no se envuelven. Cuando una petición no recibe una respuesta completa (fallo de DNS, conexión reiniciada, un cuerpo cortado a mitad de lectura), el error original de fetch se lanza tal cual, después de los posibles reintentos.
  • Errores de archivo. En Node.js, una ruta de put() que no se puede abrir lanza un Error simple (Cannot open file: <path>, con el error original en cause). En un navegador, una ruta falla con el error de importar node:fs.
  • La falta de @aws-sdk/client-s3. s3() lanza el error de importación del módulo.

UNKNOWN_ERROR

UNKNOWN_ERROR es el único código que crea el propio SDK. Se usa cuando la respuesta no tiene código de error: un cuerpo que no es JSON (la página de error de un proxy, por ejemplo) o una respuesta 2xx sin status: "success". status sigue conteniendo el estado HTTP real.

Fallos por objeto

Las operaciones por lotes indican los fallos en su resultado en lugar de lanzar un error:
  • update(): cada resultado tiene ok: false y un code.
  • delete([ids]): los objetos inexistentes van a not_found, y los demás fallos a failed.

Códigos de error

BlobErrorCode es la lista de códigos propia de la API de Blob Storage. No es la misma lista que la de los códigos de error de la API principal de Square Cloud. Para el estado HTTP y el significado de cada código, consulta la referencia de errores de la API de Blob.
ACCESS_DENIED, RATE_LIMITED, MISSING_SCOPE, RESOURCE_NOT_ALLOWED, UPLOAD_TOKEN_NOT_ALLOWED, UPLOAD_TOKEN_USED, PREFIX_NOT_ALLOWED, PERMISSION_DENIED, ACCOUNT_BLOCKED, UPGRADE_REQUIRED, STORAGE_QUOTA_EXCEEDED, PRIVATE_STORAGE_UNAVAILABLE, PUBLIC_STORAGE_UNAVAILABLE, TOO_MANY_CONCURRENT_UPLOADS, UPLOAD_FAILED, INTERNAL_SERVER_ERROR, NOT_FOUNDRATE_LIMIT está obsoleto: el servicio ya no lo envía (consulta RATE_LIMITED), pero sigue en el tipo.
OBJECT_NOT_FOUND, OBJECT_ALREADY_EXISTS, OBJECT_IS_LEGACY, CHECKSUM_MISMATCH, INVALID_CONTENT_TYPE, FILE_TOO_LARGE, FILE_TOO_SMALL, BLOCKED_FILE_TYPE, INVALID_FILE_TYPE, FILE_TYPE_NOT_ALLOWED, NOTHING_TO_UPDATE, VISIBILITY_CHANGE_FAILED, UPDATE_FAILED, DELETE_FAILED, TOO_MANY_OBJECTS, SAME_OBJECT, INVALID_DESTINATION, COPY_FAILED, PREFIX_REQUIRED, INVALID_CONTINUATION_TOKEN
TOO_MANY_CONCURRENT_CHUNKS, TOO_MANY_OPEN_UPLOADS, INVALID_UPLOAD_TOKEN, UPLOAD_NOT_FOUND, NO_CHUNKS_UPLOADED, EMPTY_CHUNK, INVALID_CHUNK_PART, CHUNK_TOO_SMALL, CHUNK_TOO_LARGE
TOO_MANY_RULES, DUPLICATE_RULE_PREFIX, INVALID_RULES, UPLOAD_TOKEN_TOO_LARGE, TOO_MANY_SHARES, SHARE_NOT_FOUND, INVALID_SHARE, API_KEY_REQUIRED, LEGACY_API_KEY
Cualquier código INVALID_*, como INVALID_OBJECT, INVALID_OBJECT_NAME o INVALID_RULE_PREFIX. Los errores de reglas llevan el prefix problemático en error.extra.
UNKNOWN_ERROR: la respuesta no tenía código de error (consulta más arriba).
BlobErrorCode también acepta cualquier otro string, de modo que un código que el servicio añada más adelante sigue pasando la comprobación de tipos.

Política de reintentos

El SDK solo reintenta lo que es seguro repetir: las llamadas GET y las partes de las subidas multipart (cada número de parte se puede volver a enviar). Una llamada reintentable se reintenta ante:
  • un error de red (incluido un cuerpo cortado a mitad de lectura);
  • cualquier respuesta 5xx;
  • TOO_MANY_CONCURRENT_CHUNKS en una parte multipart: el servidor rechaza la parte antes de leerla, así que se vuelve a enviar dentro del mismo presupuesto.
Nunca se reintenta ante cualquier otro 4xx, incluido el 429. RATE_LIMITED puede ser un bloqueo de la cuenta que dura unos 30 minutos, así que el SDK deja la decisión en tus manos.

Backoff

Antes del reintento n (empezando en 0), el SDK espera:
Es decir, backoff exponencial con un máximo de 8 segundos, con un jitter de entre el 50 % y el 100 % del retardo. Con el valor por defecto maxRetries: 2, una llamada hace como máximo 3 intentos.

Reintentar escrituras por tu cuenta

Una escritura que falla con un error de red o un 5xx puede haberse aplicado o no. Reinténtala solo cuando repetirla sea seguro para ti, por ejemplo un put() al mismo name con overwrite: true.
No reintentes un 429 RATE_LIMITED en un bucle cerrado: superar el presupuesto de toda la cuenta puede bloquear la cuenta durante unos 30 minutos. Consulta la referencia de errores de la API de Blob.

Timeouts

No hay timeout en el cliente ni forma de cancelar una llamada: una petición dura lo que espere fetch.