API 错误代码及解决方法

对 Square Cloud API 的每个失败请求都会返回一个 HTTP 状态和一个 JSON 响应体，其中带有机器可读的 code。本页按领域列出所有代码。每个端点页面也会列出该端点最常返回的代码。

Blob Storage 有自己的代码列表，AI Gateway 则使用 OpenAI 错误格式和小写代码返回。两者均不在本页范围内。

错误格式

{
  "status": "error",
  "code": "APP_NOT_FOUND",
  "message": "Optional explanation for humans."
}

字段	说明
`status`	失败时始终为 `"error"`。
`code`	错误代码，格式为 `UPPER_SNAKE_CASE`。请根据此字段进行分支处理。
`message`	可选。面向人类的说明，随时可能变化，因此可以展示给用户，但切勿解析它。

代码列表会随时间增加。遇到不认识的代码时，请按其附带的 HTTP 状态将其视为一般性失败：4xx 时修正请求，429 时等待，5xx 时稍后重试。

重试

API 不会发送 Retry-After 请求头，因此由你自行决定。一种安全的策略如下：

响应	处理方式
`400`、`401`、`403`、`404`、`409`、`413`、`415`	不要重试同一个请求：它会以同样的方式失败。请先修正输入、凭证或套餐。
`429`	在下一个请求之前等待。循环重试只会让你一直被封锁。参见速率限制。
`503 UPLOAD_BUSY`、`503 ANALYTICS_BUSY`	短暂等待后以指数退避方式重试。
`503 DATABASE_UNAVAILABLE`	几秒后重试读取操作。写入操作可能已经生效，因此在重复之前请先检查资源。
`500` 及其他 `5xx`	以退避方式重试一到两次。如果持续失败，请查看服务状态。

202 SNAPSHOT_PROCESSING 为了兼容性保留了错误结构，但它不是失败：快照仍在生成中，完成后会自行出现在列表中。不要再次请求。

速率限制

有两个代码会返回 429，含义不同：

RATE_LIMITED：账户或 API 密钥的请求额度，按每 60 秒计算，由套餐决定（参见各套餐的数值）。超出后，API 会拒绝你的请求，最长 30 分钟。少数端点在触及自身限制时也会返回 RATE_LIMITED，持续发送不属于任何账户的 API 密钥的 IP 地址也会被短暂封锁。
KEEP_CALM：单个端点自身的限制，例如每隔几秒只能重启一次。稍等片刻后重试即可。每个端点的限制写在其页面中。

身份验证与权限

代码	HTTP	含义与解决方法
`ACCESS_DENIED`	401	API 密钥缺失、输入错误、已吊销或已过期，或其所属账户已不存在。请在账户安全设置中检查密钥，不要循环重试。
`MISSING_SCOPE`	403	密钥有效，但缺少此端点所需的权限范围。权限范围无法编辑，请创建一个具有该权限范围的新密钥。参见权限范围。
`RESOURCE_NOT_ALLOWED`	403	密钥仅限于不包含此资源的应用和数据库，或者该端点作用于整个账户而密钥受到了限制。请使用涵盖该资源的密钥。
`PERMISSION_DENIED`	403	你在 workspace 中的角色不允许对共享应用执行此操作，例如没有 `admin` 角色却读取 `.env`。参见 workspace 角色。
`SCOPE_NOT_GRANTABLE`	403	受限的 API 密钥试图授予超出其自身的访问权限，例如用缺少 `envs:write` 的密钥添加 `admin` 成员。请使用拥有该角色全部权限范围的密钥，或改用控制台。
`UPGRADE_REQUIRED`	402 / 403	该功能需要更高的套餐：数据库、自定义域名和 workspace 需要 Standard 及以上，网络日志和性能分析需要 Pro 及以上，列出账户快照需要有效套餐（`402`）。`message` 会尽可能注明所需套餐。

请求校验

代码	HTTP	含义与解决方法
`INVALID_JSON_BODY`	400	请求体不是有效的 JSON。请发送 `Content-Type: application/json` 和格式正确的请求体。
`INVALID_INPUT`	400	某个字段未通过校验。`message` 会指出是哪一个。
`INVALID_ID`	400	必需的 ID（通常是 `workspaceId`）缺失或格式错误。
`INVALID_CONTENT_TYPE`	415	上传和提交需要 `multipart/form-data`，并将 zip 放在 `file` 字段中。
`PAYLOAD_TOO_LARGE`	413	请求体超出了此端点接受的大小。
`ROUTE_NOT_FOUND`	404	路径或 HTTP 方法错误。请与端点页面对照。

配额与连接限制

代码	HTTP	含义与解决方法
`RATE_LIMITED`	429	已达到账户或密钥的请求额度，或端点自身的限制。参见速率限制。
`KEEP_CALM`	429	短时间内对此端点的请求过多。稍等片刻后重试。
`DAILY_SNAPSHOTS_LIMIT_REACHED`	429	套餐每 24 小时的手动快照额度已用完。请等待后再创建，或升级以获得更多额度。
`REALTIME_MAX_CONNECTIONS`	429	你的账户已打开 5 个实时连接。请先关闭一个。
`REALTIME_MAX_CONNECTIONS_APP`	429	该应用在所有用户中已打开 30 个实时连接。

应用

代码	HTTP	含义与解决方法
`APP_NOT_FOUND`	404	应用不存在、不属于你，或者你不是共享该应用的 workspace 的成员。请检查 ID。当请求体缺少 `appId` 时，workspace 路由会返回 `400`。
`CONTAINER_ALREADY_STARTED`	409	应用或数据库已在运行。可以将其视为成功。
`CONTAINER_ALREADY_STOPPED`	409	应用或数据库已停止。可以将其视为成功。
`CONTAINER_TEMPORARILY_SUSPENDED`	409	该资源已被暂停。请查看账户邮箱了解原因。
`CONTAINER_NOT_FOUND`	409	在资源所在的服务器上找不到其容器。请稍后重试，如果问题持续，请联系支持团队。
`CONTAINER_INSUFFICIENT_DISK_SPACE`	409	磁盘空间不足，无法启动。删除不需要的文件后重试。
`CONTAINER_NETWORK_CONFLICT`	409	网络或端口冲突导致无法启动。请稍后重试。
`ACTION_FAILED`	409	启动、停止或重启因其他原因被拒绝，例如正在部署中。请检查状态后重试。
`RESTORE_IN_PROGRESS`	403	该资源正在进行快照恢复。请等待恢复完成后再删除应用，或启动、停止、删除数据库。
`DELETE_FAILED`	404	托管该资源的节点拒绝了删除。请重试。在文件管理器中，同一代码会返回 `400`。
`LOGS_UNAVAILABLE`	404	无法读取日志：应用处于离线状态、从未部署过，或节点没有响应。请稍后重试。
`METRICS_NOT_SUPPORTED`	400	仅为至少分配 512 MB RAM 的应用收集指标。

上传与提交

代码	HTTP	含义与解决方法
`INVALID_FILE`	400	表单的 `file` 字段中没有文件。
`INVALID_FILENAME`	400	文件名包含路径分隔符、`..` 或控制字符。
`INVALID_PATH`	400	提交的 `path` 包含路径穿越或 shell 字符。
`FILE_TOO_LARGE`	413	zip 超过 100 MB。
`UPLOAD_ABORTED`	400	上传完成前连接已关闭。请重新上传。
`UPLOAD_BUSY`	503	平台上正在进行的上传过多。短暂等待后重试。
`STORAGE_UPLOAD_FAILED`	400	无法存储 zip。请稍后重试。
`UPLOAD_FAILED`	400	无法处理此次上传。请重试，如果再次出现，请检查 zip。
`COMMIT_FAILED`	400	无法应用此次提交。请重试，如果再次出现，请检查 zip。
`INSUFFICIENT_MEMORY`	400	你的套餐没有足够的空闲内存来容纳该应用或数据库，或者 `MEMORY` 低于最小值：256 MB，带 `SUBDOMAIN` 的网站为 512 MB。请调整 `MEMORY`、删除部分资源或升级套餐。
`CLUSTER_SELECTION_FAILED`	400	目前没有服务器有空间容纳新的应用或数据库。请稍后重试。
`CLUSTER_MAINTENANCE_TRY_LATER`	503	因维护暂停创建新的应用和数据库。请稍后重试。
`EMPTY_RESPONSE`	400	接收上传的服务器没有返回可用的响应，因此应用未被创建。请重新上传。

zip 与配置检查

当你上传应用时，将要运行它的服务器会检查 zip 及其配置文件（squarecloud.app 或 squarecloud.config）。检查失败时会返回 400 和以下代码之一，且不会部署任何内容。请修正 zip 后重新上传。提交不会读取配置文件：在此列表中，它只可能因 FAILED_EXTRACT 或 CONTAINER_INSUFFICIENT_DISK_SPACE 而失败。

代码	HTTP	含义与解决方法
`FAILED_EXTRACT`	400	无法解压 zip。请使用标准的 zip 工具重新创建，并确认文件没有损坏。
`DOWNLOAD_FAILED`	400	服务器在收到 zip 后无法获取它。请重新上传。
`MISSING_CONFIG`	400	zip 根目录下没有 `squarecloud.app` 或 `squarecloud.config`，或者该文件为空。
`MISSING_MEMORY`、`MISSING_DISPLAY_NAME`、`MISSING_VERSION`	400	配置文件中的某个必填字段缺失或为空。代码指出的是第一个缺失的字段。
`MISSING_MAIN`	400	配置中既没有 `MAIN` 也没有 `RUNTIME`。请设置其中之一。
`INVALID_MAIN`	400	`MAIN` 包含字母、数字、`_`、`.`、`/` 和 `-` 以外的字符，或超过 32 个字符。在没有 `RUNTIME` 的情况下，如果该文件不在 zip 中、为空、指向项目之外，或没有扩展名、扩展名不对应任何受支持的语言，也会失败。
`INVALID_RUNTIME`	400	`RUNTIME` 不是配置文件参考中列出的受支持值之一。
`INVALID_VERSION`	400	`VERSION` 必须为 `recommended` 或 `latest`。不接受具体的版本号。
`INVALID_START`	400	`START` 超过 256 个字符。
`INVALID_DEPENDENCY`	400	该语言的依赖文件缺失或为空：JavaScript 和 TypeScript 为 `package.json`，Python 为 `requirements.txt` 或 `pyproject.toml`，Go 为 `go.mod` 或 `go.work`，Rust 为 `Cargo.toml`，Ruby 为 `Gemfile`，Elixir 为 `mix.exs`。
`INVALID_DISPLAY_NAME`	400	`DISPLAY_NAME` 必须为 1 到 32 个字符：字母、数字、空格、`_` 和 `-`。
`INVALID_DESCRIPTION`	400	`DESCRIPTION` 超过 280 个字符。
`INVALID_SUBDOMAIN`	400	`SUBDOMAIN` 格式错误、为保留名称或已被占用。请换一个。
`CONTAINER_INSUFFICIENT_DISK_SPACE`	400	提交时磁盘空间不足以容纳新文件。删除不需要的文件后重新提交。
`ACCESS_FORBIDDEN`	400	服务器无法为此次上传加载你的账户。请重试，如果问题持续，请联系支持团队。

环境变量

代码	HTTP	含义与解决方法
`STATIC_APP_ENV_NOT_SUPPORTED`	400	静态网站不支持环境变量。
`INVALID_ENV_CONTENT`	400	`envs` 缺失或结构错误：添加或替换时应为对象，删除时应为键的数组。
`TOO_MANY_ENV_VARS`	400	应用的变量将超过 256 个。
`ENV_NAME_TOO_LONG`	400	某个键超过 1024 个字符，或不是字符串。
`ENV_CONTENT_TOO_LONG`	400	某个值超过 4096 个字符。
`READ_FAILED`	400	无法从应用读取变量。请重试。证书路由也使用同一代码。

文件

代码	HTTP	含义与解决方法
`INVALID_PATH`	400	路径包含路径穿越或无效字符、超过 256 个字符，或者移动操作的源和目标相同。
`BLOCKED_PATH`	403	路径位于受保护的目录中，或者你在 workspace 中的角色无法写入该文件。
`INVALID_ENCODING`	400	`encoding` 只接受 `base64`。
`INVALID_CONTENT`	400	`content` 缺失、结构不受支持，或不是有效的 base64。
`FILE_NOT_FOUND`	404	该路径下没有文件或目录。
`FILE_TOO_LARGE`	413	文件管理器读写的文件最大为 10 MB。更大的文件请使用提交。
`RENAME_FAILED`	400	无法移动或重命名该文件。请重试。
`DELETE_FAILED`	400	无法删除该文件。请重试。
`INVALID_DISPLAY_NAME`、`INVALID_DESCRIPTION`、`INVALID_MEMORY`、`INVALID_AUTORESTART`、`INVALID_SUBDOMAIN`	400	写入配置文件时某个字段未通过校验，或 `SUBDOMAIN` 已被占用。请修正该字段。
`CANNOT_SET_SUBDOMAIN`	400	网站的配置中没有 `SUBDOMAIN`。网站必须始终保留一个，请重新设置。
`SAVE_FAILED`	500	无法保存新配置。请重试。

部署与 GitHub

代码	HTTP	含义与解决方法
`INVALID_ACCESS_TOKEN`	400	webhook 令牌既不是 GitHub 令牌（`ghp_...`、`github_pat_...`），也不是 `@`。
`MISSING_REQUIRED_FIELDS`	400	缺少 `repositoryName` 或 `repositoryBranch`。
`INVALID_BRANCH_LENGTH`	400	分支名称超过 256 个字符。
`BRANCH_NOT_FOUND`	400	仓库中不存在该分支。
`GIT_ALREADY_CONFIGURED`	400	该应用已关联了一个仓库。请先取消关联。
`GIT_NOT_CONFIGURED`	400	该应用没有可取消关联的仓库。
`GITHUB_NOT_CONNECTED`	403	你的 Square Cloud 账户没有可用的 GitHub 连接。请在控制台中连接或重新连接 GitHub。
`REPOSITORY_NOT_AVAILABLE`	403	Square Cloud GitHub App 未通过你的 GitHub 账户安装在该仓库上。
`REPOSITORY_PERMISSION_REQUIRED`	403	你的 GitHub 账户需要对该仓库具有写入权限。
`REPOSITORY_NOT_FOUND`	404	仓库不存在，或者你的 GitHub 账户无法看到它。
`REPOSITORY_BRANCH_ALREADY_CONFIGURED`	409	另一个应用（无论属于哪个账户）已在使用该仓库和分支。
`FAILED_TO_FETCH`	502	GitHub 没有确认该分支。请重试。
`VALIDATION_FAILED`	500 / 502	无法验证该仓库。请重试。
`VALIDATION_TIMEOUT`	504	验证仓库耗时过长。请重试。

Git 部署失败不是 HTTP 错误：它会作为 state: "error" 的事件出现在部署历史中，并带有 DEPLOY_FAILED 等 code。

网络与域名

代码	HTTP	含义与解决方法
`INVALID_TIME_RANGE`	400	`start` 或 `end` 缺失或格式错误，或者 `start` 晚于 `end`。
`INVALID_FILTER`	400	分析端点的某个筛选器格式错误。
`UNABLE_TO_FETCH_ANALYTICS`、`UNABLE_TO_FETCH_ERRORS`、`UNABLE_TO_FETCH_PERFORMANCE`	500	边缘服务商没有返回数据。请稍后重试。
`ANALYTICS_BUSY`	503	整个平台的网络分析正忙。短暂等待后重试。
`NO_CUSTOM_DOMAIN`	400	该应用没有自定义域名，因此没有可显示的 DNS 记录。
`INVALID_DOMAIN`	400	该值不是有效的域名。
`RESERVED_DOMAIN`	400	Square Cloud 自有的域名及其子域名不能用作自定义域名。
`DOMAIN_ALREADY_EXISTS`	409	另一个账户已在使用该域名。请先在那里将其移除。
`LOAD_BALANCER_LIMIT_REACHED`	403	你的套餐不允许在更多应用上使用该域名。`message` 会给出上限。
`DNS_FAILED`	502	边缘服务商无法绑定该域名。你之前的域名保持不变。请重试。
`PURGE_CACHE_FAILED`	500	缓存清除未完成。请稍后重试。

快照

代码	HTTP	含义与解决方法
`SNAPSHOT_PROCESSING`	202	不是错误：快照仍在生成中。几分钟后查看列表。
`SNAPSHOT_FAILED`	404	无法创建快照。请稍后重试。
`MISSING_PARAMETERS`	400	缺少 `snapshotId` 或 `versionId`。
`INVALID_SNAPSHOT_ID`	400	`snapshotId` 不是快照列表中的 `name`。
`INVALID_VERSION_ID`	400	`versionId` 不是快照列表中的 `version_id`。
`SNAPSHOT_NOT_FOUND`	404	没有与该 ID 和版本匹配的快照。
`SNAPSHOT_RESTORE_FAILED`	404	恢复失败。请重试，或恢复另一个快照。
`SNAPSHOT_DATABASE_MISMATCH`	400	该快照来自与目标数据库不同的数据库引擎。
`INVALID_SCOPE`	400	账户快照列表的 `scope` 必须为 `applications` 或 `databases`。

数据库

代码	HTTP	含义与解决方法
`DATABASE_NOT_FOUND`	404	数据库不存在或不属于你。
`INVALID_NAME`	400	名称必须为 1 到 32 个字符。workspace 遵循相同的规则。
`INVALID_DATABASE_TYPE`	400	`type` 必须为 `mongo`、`mysql`、`postgres` 或 `redis`。
`INVALID_DATABASE_VERSION`	400	该引擎不提供此版本。
`INVALID_MEMORY`	400	该内存值对此引擎或套餐无效。
`DATABASE_CREATION_FAILED`	400 / 500	无法创建数据库。没有留下任何残留，因此可以重试。
`DATABASE_NOT_RUNNING`	400	在读取证书或重置凭证之前，请先启动数据库。
`INVALID_RESET_TYPE`	400	`reset` 必须为 `password` 或 `certificate`。
`RESET_FAILED`	500	无法重置凭证。请重试。
`NO_UPDATE_DATA`	400	更新数据库时请发送 `name`、`ram` 或两者。

Workspace

代码	HTTP	含义与解决方法
`WORKSPACE_NOT_FOUND`	404	workspace 不存在，或者你既不是其拥有者也不是其成员。
`WORKSPACE_LIMIT_REACHED`	400	你的账户拥有的 workspace 已达到套餐允许的上限。
`WORKSPACE_CREATION_FAILED`	400	无法创建 workspace。请重试。
`INVALID_CODE`	400	邀请码缺失、格式错误或已过期。请向对方索取新的邀请码。
`INVALID_GROUP`	400	`group` 必须为 `view`、`manager`、`maintain` 或 `admin`。
`CANNOT_INVITE_OWNER`	400	该邀请码是你自己的，而你已经拥有该 workspace。
`CANNOT_EDIT_OWNER`	400	无法更改拥有者的角色。
`CANNOT_LEAVE_OWNER`	400	拥有者不能退出 workspace。请改为删除它。
`MEMBERS_LIMIT_REACHED`	400	该 workspace 的成员已达到拥有者套餐允许的上限。
`MEMBER_ALREADY_ADDED`	400	此人已经是成员。
`MEMBER_NOT_FOUND`	400 / 404	缺少 `memberId`（`400`），或此人已不再是成员（`404`）。
`APPLICATIONS_LIMIT_REACHED`	400	该 workspace 已共享 100 个应用。
`APP_ALREADY_IN_WORKSPACE`	400	该应用已在此 workspace 中共享。

平台

代码	HTTP	含义与解决方法
`INTERNAL_SERVER_ERROR`	500	意外故障。请重试一次，如果问题持续，请联系支持团队。
`DATABASE_UNAVAILABLE`	503	平台数据库暂时不可用。请几秒后重试。在此状态下，已存在的资源绝不会被报告为未找到。
`CLUSTER_TIMEOUT`	400	托管该资源的服务器未能及时响应。请重试。
`CLUSTER_UNAVAILABLE`	400	目前无法连接托管该资源的服务器。请稍后重试。
`REQUEST_ABORTED`	400	在托管该资源的服务器响应之前，请求已被取消。请重试。
`INVALID_PARAMETERS`	400	某个内部请求格式错误。请重试，如果问题持续，请联系支持团队。

AI_* 代码（AI_DAILY_LIMIT_REACHED、AI_NO_PLAN_LIMIT_REACHED、AI_MAX_CONCURRENT_STREAMS、AI_UNAVAILABLE）属于控制台的 AI 助手，需要控制台会话。API 密钥永远不会收到这些代码。

入门

账户

应用

数据库

工作区

AI

API 错误代码及解决方法

错误格式

重试

速率限制

身份验证与权限

请求校验

配额与连接限制

应用

上传与提交

zip 与配置检查

环境变量

文件

部署与 GitHub

网络与域名

快照

数据库

Workspace

平台

相关内容

​错误格式

​重试

​速率限制

​身份验证与权限

​请求校验

​配额与连接限制

​应用

​上传与提交

​zip 与配置检查

​环境变量

​文件

​部署与 GitHub

​网络与域名

​快照

​数据库

​Workspace

​平台

​相关内容

错误格式

重试

速率限制

身份验证与权限

请求校验

配额与连接限制

应用

上传与提交

zip 与配置检查

环境变量

文件

部署与 GitHub

网络与域名

快照

数据库

Workspace

平台

相关内容