*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 页面也列出了其方法最常返回的代码。任何调用还可能返回 401ACCESS_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 错误。
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:短时间内对同一路由的调用过多。
后续步骤
API 错误参考
所有错误代码及其含义和解决方法。
限制与约束
各套餐的请求限制。

