错误 - Square Cloud

所有错误的结构都相同。code 是稳定的，供你的代码使用；message（如果存在）是面向人的说明，可能会变化。

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

只在 429 和 5xx 时使用退避策略重试。除 429 以外的所有 4xx 都意味着请求本身需要修改。

身份验证与限制

代码	HTTP	含义
`ACCESS_DENIED`	401	凭证缺失或无法识别。
`PERMISSION_DENIED`	401	账户没有有效的付费计划，而此操作需要付费计划。
`MISSING_SCOPE`	403	API key 缺少该路由所需的 scope。参见身份验证。
`RESOURCE_NOT_ALLOWED`	403	API key 限定于特定应用。
`UPLOAD_TOKEN_NOT_ALLOWED`	403	上传令牌只能用于上传路由。
`UPLOAD_TOKEN_USED`	401	上传令牌已没有剩余使用次数。已过期的令牌返回 `ACCESS_DENIED`。
`ACCOUNT_BLOCKED`	403	该账户已被禁止存储文件。请联系支持团队。
`UPGRADE_REQUIRED`	403	该选项不包含在你的计划中。`message` 会指明可解锁它的计划。
`RATE_LIMIT`	429	账户级 API 预算已用尽，或该 IP 发送了过多无效凭证。
`RATE_LIMITED`	429	已达到该路由自身的限制。请等待后重试。

对象

代码	HTTP	含义
`INVALID_OBJECT`	400	对象 id 格式错误或不属于你。
`INVALID_OBJECT_NAME`	400	`name` 不符合允许的模式（1 到 128 个字符）。
`INVALID_OBJECT_PREFIX`	400	`prefix` 不符合允许的模式。
`INVALID_OBJECT_EXPIRE`	400	`expire` 不是有效的时长（1 小时到 1825 天）。
`INVALID_OBJECT_PRIVATE`	400	`private` 不是 `true` 或 `false`。
`INVALID_OBJECT_SECURITY_HASH`	400	`security_hash` 不是布尔值，或在私有对象上为 `false`。
`INVALID_OBJECT_OVERWRITE`	400	`overwrite` 不是 `true` 或 `false`。
`INVALID_OBJECT_DISPOSITION`	400	`disposition` 不是 `inline` 或 `attachment`。
`INVALID_OBJECT_CACHE_CONTROL`	400	`cache_control` 不是 `immutable`、`no-cache` 或 `max-age=60..31536000`。
`INVALID_OBJECT_METADATA`	400	`metadata` 格式错误、使用了保留键，或超过 5 个键或 512 字节。
`INVALID_STORAGE_AUTO_DOWNLOAD`	400	`auto_download` 不是 `true` 或 `false`。
`INVALID_CHECKSUM`	400	`checksum_sha256` 不是 64 个小写十六进制字符。
`CHECKSUM_MISMATCH`	400	文件与 `checksum_sha256` 不匹配。未存储任何内容。
`INVALID_DESTINATION`	400	复制的 `destination` 格式错误。
`SAME_OBJECT`	400	复制的源对象和目标对象是同一个对象。
`NOTHING_TO_UPDATE`	400	请求没有修改任何字段。
`INVALID_CONTINUATION_TOKEN`	400	列表的 `cursor` 格式错误或已失效。请不带游标重新开始。
`TOO_MANY_OBJECTS`	400	单个请求中的对象过多（删除上限 100 个，更新上限 50 个）。
`PREFIX_NOT_ALLOWED`	403	上传令牌绑定的是另一个前缀。
`OBJECT_NOT_FOUND`	404	对象不存在。
`OBJECT_ALREADY_EXISTS`	409	已存在具有该 id 的对象，且 `overwrite` 为 `false`。
`OBJECT_IS_LEGACY`	按对象	在对象更新的 `results` 中返回。该对象是 2026 年 9 月更新之前存储的旧版文件，必须先通过对象复制（`move: true`）移动，之后才能修改其响应头。
`VISIBILITY_CHANGE_FAILED`	按对象	在对象更新的 `results` 中返回：该对象无法设为私有，仍然是公开的。请重试。
`UPDATE_FAILED` / `COPY_FAILED` / `DELETE_FAILED`	500	操作失败。请重试。

上传

代码	HTTP	含义
`INVALID_CONTENT_TYPE`	409	对象上传只接受恰好包含一个文件的 `multipart/form-data`。
`INVALID_FILE`	400	文件部分缺失或无法读取。
`INVALID_FILE_TYPE`	400	文件扩展名格式错误或过长。
`BLOCKED_FILE_TYPE`	400	不接受可执行文件和安装程序。
`FILE_TYPE_NOT_ALLOWED`	400	上传令牌或前缀规则不允许该扩展名。
`FILE_TOO_SMALL`	400	文件至少需要 512 字节。
`FILE_TOO_LARGE`	413	单个请求超过 100 MB（请使用分块上传），或超过计划、令牌或规则允许的大小。
`STORAGE_QUOTA_EXCEEDED`	403	账户已达到其内置存储配额。
`TOO_MANY_CONCURRENT_UPLOADS`	429	该账户上已有 4 个上传正在进行。
`PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE`	503	存储暂时不可用。请重试。
`UPLOAD_FAILED`	500	上传失败。请重试。

分块上传

代码	HTTP	含义
`INVALID_UPLOAD_TOKEN`	400	`upload` 令牌缺失、格式错误或不属于你。
`INVALID_CHUNK_PART`	400	`part` 不是 1 到 2048 之间的整数。
`EMPTY_CHUNK`	400	分块请求体为空。
`CHUNK_TOO_LARGE`	413	某个分块超过 32 MB。
`CHUNK_TOO_SMALL`	400	除最后一个分块外，某个分块小于 5 MB。
`NO_CHUNKS_UPLOADED`	400	在发送任何分块之前就调用了完成操作。
`TOO_MANY_OPEN_UPLOADS`	429	账户已有 32 个未完成的上传。请完成或中止其中一个。
`TOO_MANY_CONCURRENT_CHUNKS`	429	该账户上已有 6 个分块正在传输。
`UPLOAD_NOT_FOUND`	404	该上传已完成、已中止或已过期。

临时链接与分享

代码	HTTP	含义
`INVALID_DOWNLOAD_EXPIRES`	400	`expires` 超出 60 到 86400 秒的范围。
`INVALID_FILENAME`	400	去除无效字符后 `filename` 为空。
`INVALID_EXPIRES_IN`	400	`expires_in` 超出允许的范围。
`INVALID_MAX_DOWNLOADS`	400	`max_downloads` 超出 1 到 10000 的范围。
`INVALID_PASSWORD`	400	密码必须为 8 到 128 个字符。
`INVALID_SHARE`	400	分享 id 格式错误。
`SHARE_NOT_FOUND`	404	该分享不存在或已被撤销。
`TOO_MANY_SHARES`	409	账户已有 1000 个有效分享。请先撤销一些。

账户设置与上传令牌

代码	HTTP	含义
`INVALID_BODY`	400	请求体缺失或不是 JSON 对象。
`INVALID_RULES`	400	`rules` 不是数组。
`TOO_MANY_RULES`	400	在 Enterprise 上超过 20 条规则。在其他计划上，超出计划上限（Hobby 和 Standard 5 条，Pro 10 条）会返回 `UPGRADE_REQUIRED`。
`INVALID_RULE_PREFIX` / `DUPLICATE_RULE_PREFIX`	400	某条规则的前缀格式错误，或与另一条规则的前缀重复。
`INVALID_RULE_PRIVATE` / `INVALID_RULE_EXPIRE` / `INVALID_RULE_MAX_SIZE` / `INVALID_RULE_EXTENSIONS` / `INVALID_RULE_CACHE_CONTROL` / `INVALID_RULE_DELETE_AFTER`	400	某个规则字段无效。响应中会带上该规则的 `prefix`。
`INVALID_EXPIRES_IN` / `INVALID_MAX_USES` / `INVALID_MAX_SIZE` / `INVALID_ALLOWED_EXTENSIONS`	400	某个上传令牌字段超出范围。
`UPLOAD_TOKEN_TOO_LARGE`	400	令牌选项无法装入一个令牌。请缩短元数据或扩展名列表。

S3 凭证

代码	HTTP	含义
`API_KEY_REQUIRED`	400	S3 凭证由 API key 派生，而不是由控制台会话派生。
`LEGACY_API_KEY`	400	该 API key 使用旧格式。请在账户设置中创建一个新 key。
`INVALID_CREDENTIAL`	401	无法验证该 API key。

S3 网关则返回标准的 S3 XML 错误。

全局

代码	HTTP	含义
`ROUTE_NOT_FOUND` / `NOT_FOUND`	404	路由不存在。
`INTERNAL_SERVER_ERROR`	500	意外故障。请稍后重试。

入门

对象

分块上传

账户

分享链接

S3

错误

身份验证与限制

对象

上传

分块上传

临时链接与分享

账户设置与上传令牌

S3 凭证

全局

​身份验证与限制

​对象

​上传

​分块上传

​临时链接与分享

​账户设置与上传令牌

​S3 凭证

​全局

身份验证与限制

对象

上传

分块上传

临时链接与分享

账户设置与上传令牌

S3 凭证

全局