Skip to main content

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 错误参考。
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 已弃用:服务不再发送它(参见 RATE_LIMITED),但它仍保留在该类型中。
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
任何 INVALID_* 代码,例如 INVALID_OBJECT、INVALID_OBJECT_NAME 或 INVALID_RULE_PREFIX。规则错误会在 error.extra 中携带出错的 prefix。
UNKNOWN_ERROR:响应没有错误代码(参见上文)。
BlobErrorCode 也接受任何其他字符串,因此服务日后新增的代码仍能通过类型检查。

重试策略

SDK 只重试可以安全重复的操作:GET 调用和分片上传的分片(每个分片编号都可以再次发送)。 可重试的调用会在以下情况下重试:
  • 网络错误(包括响应体在读取中途被截断);
  • 任何 5xx 响应;
  • 分片上传的某个分片返回 TOO_MANY_CONCURRENT_CHUNKS:服务器在读取该分片之前就拒绝了它,因此会在同一预算内再次发送。
对于其他任何 4xx,包括 429,永远不会重试。RATE_LIMITED 可能是持续约 30 分钟的账户封锁,因此 SDK 将决定权留给你。

退避

在第 n 次重试(从 0 开始)之前,SDK 会等待:
也就是说,这是上限为 8 秒的指数退避,抖动在延迟的 50% 到 100% 之间。使用默认的 maxRetries: 2 时,一次调用最多进行 3 次尝试。

自行重试写操作

因网络错误或 5xx 失败的写操作可能已被应用,也可能没有。仅当重复执行对你而言是安全的时候才重试,例如对同一 name 使用 overwrite: true 的 put()。
不要在紧密循环中重试 429 RATE_LIMITED:超出账户范围的预算可能会导致账户被封锁约 30 分钟。参见 Blob API 错误参考。

超时

没有客户端超时,也无法取消调用:请求会持续到 fetch 等待结束为止。