> ## 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. # 错误 > 在 squarecloud-api 中处理 SquareCloudAPIError：状态、代码和消息，SDK 自身的代码，按分组列出的 API 代码，以及重试、超时和速率限制。 所有 API 失败和网络失败都会抛出同一个异常：`SquareCloudAPIError`。 ```python theme={"system"} 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//start" print(error) # POST /v2/apps//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)` 的格式为 ` : HTTP : `；状态为 `0` 时不含 `HTTP `，消息为空时不含 `: `。 有两种失败不会被包装： * 空的或仅含空白字符的 API 密钥会在客户端构造函数中抛出 `ValueError`。 * 本地文件问题会抛出 `OSError`：无法打开的上传路径、在上传过程中变得不可读的文件，或无法写入的 `download_snapshot` 目标。 ## SDK 代码 | 状态 | 代码 | 触发条件 | | -- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- | | 0 | `NETWORK_ERROR` | 没有响应（DNS、连接重置、响应体被截断）。原始异常位于 `cause` 中 | | 0 | `TIMEOUT` | 某次套接字操作超过了[超时](/zh/sdks/py/client#超时)时间 | | 0 | `FILE_TOO_LARGE` | 本地检查：上传超过 100 MB 或 `files.write` 超过 10 MB。未发送任何内容 | | 0 | `INVALID_ID` | 本地检查：ID 为空、`.` 或 `..`。未发送任何内容 | | 任意 | `UNKNOWN_ERROR` | 没有代码的响应（例如代理的错误页面），带有真实的 `status` 和服务器的消息，没有消息时则为 `HTTP `。不是 JSON 的 2xx 响应体的消息为 `Invalid JSON in HTTP response` | ## 代码是字符串 `code` 是普通的 `str`：SDK 没有代码枚举。`SquareCloudAPIError` 的 docstring 列出了所有已知的 API 代码，下方的分组也列出了它们。 API 代码的列表会不断增加。**请根据 HTTP 状态处理未知代码**： ```python theme={"system"} 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` `UPLOAD_BUSY`, `UPLOAD_FAILED`, `UPLOAD_ABORTED`, `STORAGE_UPLOAD_FAILED`, `COMMIT_FAILED`, `READ_FAILED`, `SAVE_FAILED`, `RENAME_FAILED`, `DELETE_FAILED`, `REQUEST_ABORTED`, `EMPTY_RESPONSE` `SNAPSHOT_FAILED`, `SNAPSHOT_PROCESSING`, `SNAPSHOT_RESTORE_FAILED`, `SNAPSHOT_DATABASE_MISMATCH`, `RESTORE_IN_PROGRESS` `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` `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](/zh/sdks/py/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 秒下限的调用以及没有超时的调用，请参见[超时](/zh/sdks/py/client#超时)。超时会抛出状态为 `0` 的 `TIMEOUT`，且从不重试。 ## 速率限制 每个账户都有每 60 秒的请求数限制，由其套餐决定（[具体数值](/zh/api-reference/limitations-and-restrictions)），部分路由还有各自的限制： * **429 `RATE_LIMITED`**：账户、API 密钥或 IP 被封锁，可能持续约 30 分钟。也是网络 endpoint 和 `account.snapshots` 的限制。 * **429 `KEEP_CALM`**：短时间内对同一路由的调用过多。 SDK 从不重试 429。请放慢速度，并在再次尝试之前等待。