Skip to main content
所有 API 失败、网络失败和本地失败都是同一个类型:*squarecloud.APIError。请使用 errors.As 检查它。 下面较短的代码片段在运行示例中的程序里运行:每次将一个片段粘贴到 main 中,然后运行 goimports。

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 自身的代码。CodeRateLimit(RATE_LIMIT)和 CodeRateLimitExceeded(RATE_LIMIT_EXCEEDED)仍然导出,并被标记为已弃用:API 现在对这两者都返回 RATE_LIMITED(CodeRateLimited)。 API 代码的列表会不断增加。请根据 HTTP 状态处理未知代码:

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……),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 密钥超出了请求配额,会被封锁约 30 分钟;或者某个 IP 持续发送无效密钥,会被短时间封锁。也是网络 endpoint 和 Account.Snapshots 的限制。
  • 429 KEEP_CALM:短时间内对同一路由的调用过多。
SDK 从不重试 429。请放慢速度,并在再次尝试之前等待。

后续步骤

API 错误参考

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

限制与约束

各套餐的请求限制。