Python SDK：错误与重试

所有 API 失败和网络失败都会抛出同一个异常：SquareCloudAPIError。示例使用创建客户端中的 client。app_id 是你的某个应用的 ID：client.account.me() 会列出它们。

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 代码。RATE_LIMIT 和 RATE_LIMIT_EXCEEDED 仍在其中，并被标记为已弃用：API 现在对这两者都返回 RATE_LIMITED。 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

API 错误代码

其他所有代码都来自 API。API 错误参考列出了每个代码及其 HTTP 状态、含义和解决方法，每个 SDK 页面也列出了其方法最常返回的代码。任何调用还可能返回 401 ACCESS_DENIED（密钥有误）、403 MISSING_SCOPE 或 RESOURCE_NOT_ALLOWED（密钥的限制）、429（参见速率限制）或 503 DATABASE_UNAVAILABLE。 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 密钥超出了请求配额，会被封锁约 30 分钟；或者某个 IP 持续发送无效密钥，会被短时间封锁。也是网络 endpoint 和 account.snapshots 的限制。
429 KEEP_CALM：短时间内对同一路由的调用过多。

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

后续步骤

API 错误参考

所有错误代码及其含义和解决方法。

限制与约束

各套餐的请求限制。

CLI

VS Code

SDKs

Python SDK：错误与重试

`SquareCloudAPIError`

SDK 代码

代码是字符串

API 错误代码

重试

超时

速率限制

后续步骤

API 错误参考

限制与约束

​SquareCloudAPIError

​SDK 代码

​代码是字符串

​API 错误代码

​重试

​超时

​速率限制

​后续步骤

API 错误参考

限制与约束

`SquareCloudAPIError`

SDK 代码

代码是字符串

API 错误代码

重试

超时

速率限制

后续步骤