> ## Documentation Index > Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt > Use this file to discover all available pages before exploring further. # 错误 > Blob Storage API 返回的所有错误代码，及其 HTTP 状态码和处理方式。 所有错误的结构都相同。`code` 是稳定的，供你的代码使用；`message`（如果存在）是面向人的说明，可能会变化。 ```json theme={null} { "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。参见[身份验证](/zh/blob-reference/authentication)。 | | `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` | 按对象 | 在[对象更新](/zh/blob-reference/endpoint/update)的 `results` 中返回。该对象是 2026 年 9 月更新之前存储的旧版文件，必须先通过[对象复制](/zh/blob-reference/endpoint/copy)（`move: true`）移动，之后才能修改其响应头。 | | `VISIBILITY_CHANGE_FAILED` | 按对象 | 在[对象更新](/zh/blob-reference/endpoint/update)的 `results` 中返回：该对象无法设为私有，**仍然是公开的**。请重试。 | | `UPDATE_FAILED` / `COPY_FAILED` / `DELETE_FAILED` | 500 | 操作失败。请重试。 | ## 上传 | 代码 | HTTP | 含义 | | ------------------------------------------------------------ | ---- | --------------------------------------------------------------------------- | | `INVALID_CONTENT_TYPE` | 409 | [对象上传](/zh/blob-reference/endpoint/post)只接受恰好包含一个文件的 `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 网关](/zh/blob-reference/s3-compatibility)则返回标准的 S3 XML 错误。 ## 全局 | 代码 | HTTP | 含义 | | ------------------------------- | ---- | ----------- | | `ROUTE_NOT_FOUND` / `NOT_FOUND` | 404 | 路由不存在。 | | `INTERNAL_SERVER_ERROR` | 500 | 意外故障。请稍后重试。 |