错误 - Square Cloud

所有 API 失败和网络失败都会抛出同一个异常：SquareCloudAPIError。

from squarecloud import SquareCloudAPIError

try:
    client.apps.start(app_id)
except SquareCloudAPIError as error:
    print(error.status, error.code, error.message)
    print(error.method, error.path)  # "POST" "/v2/apps/<id>/start"
    print(error)  # POST /v2/apps/<id>/start: HTTP 404 APP_NOT_FOUND

`SquareCloudAPIError`

SquareCloudAPIError 是 Exception 的子类。

属性	类型	说明
`status`	`int`	HTTP 状态。没有收到响应时为 `0`（网络错误、超时、本地检查）
`code`	`str`	API 的错误代码，例如 `APP_NOT_FOUND`，或 SDK 自身的代码之一
`message`	`str`	服务器给出的说明。当服务器只发送了代码时为 `''`
`method`	`str`	失败调用的 HTTP 方法
`path`	`str`	失败调用的 URL 路径，不含查询字符串
`cause`	`BaseException \| None`	原始异常，适用于 `NETWORK_ERROR`、`TIMEOUT` 和无效 JSON（与 `__cause__` 相同）

str(error) 的格式为 <METHOD> <path>: HTTP <status> <CODE>: <message>；状态为 0 时不含 HTTP <status>，消息为空时不含 : <message>。有两种失败不会被包装：

空的或仅含空白字符的 API 密钥会在客户端构造函数中抛出 ValueError。
本地文件问题会抛出 OSError：无法打开的上传路径、在上传过程中变得不可读的文件，或无法写入的 download_snapshot 目标。

SDK 代码

状态	代码	触发条件
0	`NETWORK_ERROR`	没有响应（DNS、连接重置、响应体被截断）。原始异常位于 `cause` 中
0	`TIMEOUT`	某次套接字操作超过了超时时间
0	`FILE_TOO_LARGE`	本地检查：上传超过 100 MB 或 `files.write` 超过 10 MB。未发送任何内容
0	`INVALID_ID`	本地检查：ID 为空、`.` 或 `..`。未发送任何内容
任意	`UNKNOWN_ERROR`	没有代码的响应（例如代理的错误页面），带有真实的 `status` 和服务器的消息，没有消息时则为 `HTTP <status>`。不是 JSON 的 2xx 响应体的消息为 `Invalid JSON in HTTP <status> response`

代码是字符串

code 是普通的 str：SDK 没有代码枚举。SquareCloudAPIError 的 docstring 列出了所有已知的 API 代码，下方的分组也列出了它们。 API 代码的列表会不断增加。请根据 HTTP 状态处理未知代码：

def start(app_id: str):
    try:
        client.apps.start(app_id)
    except SquareCloudAPIError as error:
        match error.code:
            case "APP_NOT_FOUND":
                return None
            case "CONTAINER_ALREADY_STARTED":
                return  # fine
            case _:
                if error.status == 429:
                    return retry_later()
                if error.status >= 500:
                    return report_outage(error)
                raise

任何调用都可能出现的错误

状态	代码	触发条件
401	`ACCESS_DENIED`	API 密钥缺失、未知、已撤销或已过期
403	`MISSING_SCOPE`	该密钥缺少此调用所需的作用域。`message` 会指明是哪一个
403	`RESOURCE_NOT_ALLOWED`	该密钥被限制为其他应用或数据库
403	`PERMISSION_DENIED`	你的 workspace 角色不允许该操作
404	`ROUTE_NOT_FOUND`	未知路由
429	`RATE_LIMITED`	账户、密钥或 IP 被封锁（可能持续约 30 分钟），以及网络 endpoint 和 `account.snapshots` 的限制
429	`KEEP_CALM`	对该路由的请求过快
500	`INTERNAL_SERVER_ERROR`	服务器错误
503	`DATABASE_UNAVAILABLE`	平台数据库不可用。变更操作可能已经被应用

按分组列出的 API 代码

未找到

APP_NOT_FOUND, DATABASE_NOT_FOUND, WORKSPACE_NOT_FOUND, MEMBER_NOT_FOUND, FILE_NOT_FOUND, SNAPSHOT_NOT_FOUND, REPOSITORY_NOT_FOUND, BRANCH_NOT_FOUND, ROUTE_NOT_FOUND

验证

INVALID_ACCESS_TOKEN, INVALID_AUTORESTART, INVALID_BRANCH_LENGTH, INVALID_CODE, INVALID_CONTENT, INVALID_CONTENT_TYPE, INVALID_DATABASE_TYPE, INVALID_DATABASE_VERSION, INVALID_DESCRIPTION, INVALID_DISPLAY_NAME, INVALID_DOMAIN, INVALID_ENCODING, INVALID_ENV_CONTENT, INVALID_FILE, INVALID_FILENAME, INVALID_FILTER, INVALID_GROUP, INVALID_ID, INVALID_INPUT, INVALID_JSON_BODY, INVALID_MEMORY, INVALID_NAME, INVALID_PARAMETERS, INVALID_PATH, INVALID_RESET_TYPE, INVALID_SCOPE, INVALID_SNAPSHOT_ID, INVALID_SUBDOMAIN, INVALID_TIME_RANGE, INVALID_VERSION_ID, MISSING_PARAMETERS, MISSING_REQUIRED_FIELDS, NO_UPDATE_DATA, VALIDATION_FAILED, VALIDATION_TIMEOUT, ENV_NAME_TOO_LONG, ENV_CONTENT_TOO_LONG, TOO_MANY_ENV_VARS, RESERVED_DOMAIN, CANNOT_SET_SUBDOMAIN, STATIC_APP_ENV_NOT_SUPPORTED

身份验证和权限

ACCESS_DENIED, MISSING_SCOPE, RESOURCE_NOT_ALLOWED, PERMISSION_DENIED, SCOPE_NOT_GRANTABLE, BLOCKED_PATH, UPGRADE_REQUIRED

限制和速率限制

RATE_LIMITED, KEEP_CALM, APPLICATIONS_LIMIT_REACHED, WORKSPACE_LIMIT_REACHED, MEMBERS_LIMIT_REACHED, LOAD_BALANCER_LIMIT_REACHED, DAILY_SNAPSHOTS_LIMIT_REACHED, INSUFFICIENT_MEMORY, FILE_TOO_LARGE, PAYLOAD_TOO_LARGE, REALTIME_MAX_CONNECTIONS, REALTIME_MAX_CONNECTIONS_APP, AI_DAILY_LIMIT_REACHED, AI_MAX_CONCURRENT_STREAMS, AI_NO_PLAN_LIMIT_REACHED

容器（启动、停止、重启）

CONTAINER_ALREADY_STARTED, CONTAINER_ALREADY_STOPPED, CONTAINER_TEMPORARILY_SUSPENDED, CONTAINER_NOT_FOUND, CONTAINER_INSUFFICIENT_DISK_SPACE, CONTAINER_NETWORK_CONFLICT, ACTION_FAILED, DATABASE_NOT_RUNNING

上传、文件和 commit

UPLOAD_BUSY, UPLOAD_FAILED, UPLOAD_ABORTED, STORAGE_UPLOAD_FAILED, COMMIT_FAILED, READ_FAILED, SAVE_FAILED, RENAME_FAILED, DELETE_FAILED, REQUEST_ABORTED, EMPTY_RESPONSE

Snapshots

SNAPSHOT_FAILED, SNAPSHOT_PROCESSING, SNAPSHOT_RESTORE_FAILED, SNAPSHOT_DATABASE_MISMATCH, RESTORE_IN_PROGRESS

Deploy 和 GitHub

GIT_ALREADY_CONFIGURED, GIT_NOT_CONFIGURED, GITHUB_NOT_CONNECTED, REPOSITORY_BRANCH_ALREADY_CONFIGURED, REPOSITORY_NOT_AVAILABLE, REPOSITORY_PERMISSION_REQUIRED, FAILED_TO_FETCH

网络和域名

ANALYTICS_BUSY, UNABLE_TO_FETCH_ANALYTICS, UNABLE_TO_FETCH_ERRORS, UNABLE_TO_FETCH_PERFORMANCE, DNS_FAILED, DOMAIN_ALREADY_EXISTS, NO_CUSTOM_DOMAIN, PURGE_CACHE_FAILED, LOGS_UNAVAILABLE, METRICS_NOT_SUPPORTED

数据库和 workspace

DATABASE_CREATION_FAILED, DATABASE_UNAVAILABLE, RESET_FAILED, WORKSPACE_CREATION_FAILED, APP_ALREADY_IN_WORKSPACE, MEMBER_ALREADY_ADDED, CANNOT_EDIT_OWNER, CANNOT_INVITE_OWNER, CANNOT_LEAVE_OWNER, CONFLICTING_RESOURCES

平台

INTERNAL_SERVER_ERROR, CLUSTER_MAINTENANCE_TRY_LATER, CLUSTER_SELECTION_FAILED, CLUSTER_TIMEOUT, CLUSTER_UNAVAILABLE, AI_UNAVAILABLE

已弃用

RATE_LIMIT 和 RATE_LIMIT_EXCEEDED 仍在列表中，并被标记为已弃用：API 现在对这两者都返回 RATE_LIMITED。

ai.chat() 的错误则使用小写的 OpenAI 代码（access_denied、rate_limit_exceeded、server_overloaded……）。参见 AI。

重试

SDK 只重试可以安全重复的操作，最多 max_retries 次（默认 2，即最多 3 次尝试）：

重试的情况	方法
`NETWORK_ERROR`	仅 `GET`
503 `UPLOAD_BUSY`	任意方法
503 `ANALYTICS_BUSY`	任意方法
503 `DATABASE_UNAVAILABLE`	仅 `GET`

它从不重试：

TIMEOUT；
任何 429：RATE_LIMITED 可能是持续约 30 分钟的封锁，KEEP_CALM 也不会重试；
其他 5xx；
AI 错误。

503 DATABASE_UNAVAILABLE 可能在变更操作已被应用之后才到达，因此 SDK 不会在 GET 以外重试它。如有需要，请自行重试你的幂等变更操作。第 n 次重试（从 0 开始）之前的等待时间为 min(8 s, 500 ms · 2^n) · U(0.5, 1)：带有 50% 到 100% 抖动的指数退避。设置 max_retries=0 可关闭重试。

超时

timeout（30 秒）按每次套接字操作（连接以及每次读或写）计算，而不是针对整个请求。关于具有 120 秒下限的调用以及没有超时的调用，请参见超时。超时会抛出状态为 0 的 TIMEOUT，且从不重试。

速率限制

每个账户都有每 60 秒的请求数限制，由其套餐决定（具体数值），部分路由还有各自的限制：

429 RATE_LIMITED：账户、API 密钥或 IP 被封锁，可能持续约 30 分钟。也是网络 endpoint 和 account.snapshots 的限制。
429 KEEP_CALM：短时间内对同一路由的调用过多。

SDK 从不重试 429。请放慢速度，并在再次尝试之前等待。

服务

Runtimes

平台

故障排除

CLI

SDKs

Changelog

错误

`SquareCloudAPIError`

SDK 代码

代码是字符串

任何调用都可能出现的错误

按分组列出的 API 代码

重试

超时

速率限制

​SquareCloudAPIError

​SDK 代码

​代码是字符串

​任何调用都可能出现的错误

​按分组列出的 API 代码

​重试

​超时

​速率限制

`SquareCloudAPIError`

SDK 代码

代码是字符串

任何调用都可能出现的错误

按分组列出的 API 代码

重试

超时

速率限制