Skip to main content
所有 API 失败、网络失败和本地失败都是同一个类型:*squarecloud.APIError。请使用 errors.As 检查它。

APIError

对于 NETWORK_ERROR、TIMEOUT 和无效 JSON,Unwrap() 返回其原因(传输、解码或 context 错误),否则返回 nil。Error() 输出 squarecloud: <METHOD> <path>: HTTP <status> <CODE>: <message>,状态为 0 时省略 HTTP <status>,消息为空时省略 : <message>。请根据字段进行匹配,而不是依赖这段文本。

被取消和已到期的 context

ctx 被取消的调用会返回代码为 NETWORK_ERROR 的 *APIError,截止时间已过的调用会返回 TIMEOUT,两者的状态均为 0。它们可以解包为 context 的错误:
少数失败不是 *APIError:
  • 当 ctx 结束时,Realtime.Next 直接返回 ctx.Err();当流正常结束时,返回 io.EOF。
  • 调用方的问题是普通错误:nil 的上传 reader、无法解析的 snapshot URL 或基础 URL、encoding/json 无法编码的输入,以及传给 DownloadSnapshot 的 io.Writer 返回的错误。

SDK 代码

Code* 常量

Code 是一个普通的 string。该包为每个公开的 API 代码提供一个常量,以 Go 风格命名(APP_NOT_FOUND 对应 CodeAppNotFound,以及 CodeInvalidID、CodeDNSFailed……),外加上面列出的 SDK 自身的代码。 API 代码的列表会不断增加。请根据 HTTP 状态处理未知代码:

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

按分组列出的 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
CodeRateLimit(RATE_LIMIT)和 CodeRateLimitExceeded(RATE_LIMIT_EXCEEDED)仍然导出,并被标记为已弃用:API 现在对这两者都返回 RATE_LIMITED(CodeRateLimited)。
AI.Chat 的错误则使用小写的 OpenAI 代码(access_denied、rate_limit_exceeded、server_overloaded……),Code 会原样携带这些代码。参见 AI。

重试

SDK 只重试可以安全重复的操作,最多 WithMaxRetries 次(默认 2,即最多 3 次尝试): 它从不重试:
  • TIMEOUT;
  • 任何 429:RATE_LIMITED 可能是持续约 30 分钟的封锁,KEEP_CALM 也不会重试;
  • 其他 5xx;
  • AI 错误。
503 DATABASE_UNAVAILABLE 可能在变更操作已被应用之后才到达,因此 SDK 不会在 GET 以外重试它。如有需要,请自行重试你的幂等变更操作。只有当上传的请求体可以重放时才会重试:即大小已知的 io.ReaderAt,例如 *os.File(参见 Commit 与上传)。 第 n 次重试(从 0 开始)之前的等待时间为 min(8 s, 500 ms · 2^n) · U(0.5, 1):带有 50% 到 100% 抖动的指数退避。设置 WithMaxRetries(0) 可关闭重试。

超时

WithTimeout(30 秒)仅在 ctx 没有截止时间时生效,并且一个截止时间覆盖整个调用,包括重试和退避等待。关于具有 2 分钟下限的调用以及没有默认截止时间的调用,请参见超时。截止时间已过会返回状态为 0 的 TIMEOUT,从不重试,并可解包为 context.DeadlineExceeded。

速率限制

每个账户都有每 60 秒的请求数限制,由其套餐决定(具体数值),部分路由还有各自的限制:
  • 429 RATE_LIMITED:账户、API 密钥或 IP 被封锁,可能持续约 30 分钟。也是网络 endpoint 和 Account.Snapshots 的限制。
  • 429 KEEP_CALM:短时间内对同一路由的调用过多。
SDK 从不重试 429。请放慢速度,并在再次尝试之前等待。