SquareCloudBlobError
每个 API 失败都会抛出 SquareCloudBlobError。
哪些不是 SquareCloudBlobError
- 网络错误不会被包装。 当请求没有得到完整的响应时(DNS 失败、连接重置、响应体在读取中途被截断),原始的
fetch错误会在所有重试之后被原样抛出。 - 文件错误。 在 Node.js 中,无法打开的
put()路径会抛出普通的Error(Cannot open file: <path>,原始错误位于cause中)。在浏览器中,路径会以导入node:fs时的错误失败。 - 缺少
@aws-sdk/client-s3。s3()会抛出模块导入错误。
UNKNOWN_ERROR
UNKNOWN_ERROR 是 SDK 自己创建的唯一代码。当响应没有错误代码时使用:非 JSON 的响应体(例如代理的错误页面),或不带 status: "success" 的 2xx 响应。status 仍保存真实的 HTTP 状态。
单个对象的失败
批量操作会在结果中报告失败,而不是抛出异常:update():每个结果都有ok: false和一个code。delete([ids]):不存在的对象进入not_found,其他失败进入failed。
错误代码
BlobErrorCode 是 Blob Storage API 自身的代码列表。它与 Square Cloud 主 API 的错误代码不是同一个列表。关于每个代码的 HTTP 状态和含义,请参见 Blob API 错误参考。
对象
对象
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规则、上传令牌、分享和 S3
规则、上传令牌、分享和 S3
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验证(400)
验证(400)
任何
INVALID_* 代码,例如 INVALID_OBJECT、INVALID_OBJECT_NAME 或 INVALID_RULE_PREFIX。规则错误会在 error.extra 中携带出错的 prefix。SDK
SDK
UNKNOWN_ERROR:响应没有错误代码(参见上文)。BlobErrorCode 也接受任何其他字符串,因此服务日后新增的代码仍能通过类型检查。
重试策略
SDK 只重试可以安全重复的操作:GET 调用和分片上传的分片(每个分片编号都可以再次发送)。
可重试的调用会在以下情况下重试:
- 网络错误(包括响应体在读取中途被截断);
- 任何
5xx响应; - 分片上传的某个分片返回
TOO_MANY_CONCURRENT_CHUNKS:服务器在读取该分片之前就拒绝了它,因此会在同一预算内再次发送。
4xx,包括 429,永远不会重试。RATE_LIMITED 可能是持续约 30 分钟的账户封锁,因此 SDK 将决定权留给你。
退避
在第n 次重试(从 0 开始)之前,SDK 会等待:
maxRetries: 2 时,一次调用最多进行 3 次尝试。
自行重试写操作
因网络错误或5xx 失败的写操作可能已被应用,也可能没有。仅当重复执行对你而言是安全的时候才重试,例如对同一 name 使用 overwrite: true 的 put()。
超时
没有客户端超时,也无法取消调用:请求会持续到fetch 等待结束为止。
