错误码
所有接口出错时都返回统一的结构。
REST:HTTP 状态码 + JSON 正文
{"error":{"code":"not_found","message":"app \"ghost\" not found"}}
JSON-RPC:error.data.code 里是同一个字符串错误码,error.code 是对应的数字(见下表)。请按字符串错误码判断,不要依赖 message 的文字,它可能会变。
错误码一览
| code | HTTP | JSON-RPC error.code |
含义 |
|---|---|---|---|
invalid_argument |
400 | -32602 | 参数不合法:id 格式不对、缺字段、JSON 错误、versionCode 不是整数等 |
unauthorized |
401 | -32002 | 写接口没带 token,或 token 无效 / 已吊销(响应带 WWW-Authenticate: Bearer) |
forbidden |
403 | -32003 | token 无权操作这个应用,或该操作需要管理员 token |
app_delisted |
403 | -32007 | 应用已被管理员下架 |
not_found |
404 | -32001 | 应用、平台、渠道或版本不存在;渠道上还没发布过;下载的版本已被撤回 |
conflict |
409 | -32004 | versionCode 没有比已发布的大;撤回仍被渠道提供的版本;promote 已撤回的版本;创建已存在的应用 |
too_large |
413 | -32005 | 安装包超过服务端上限(默认 2 GiB) |
unavailable |
503 | -32006 | 等待中的长轮询太多;渠道提供的安装包在磁盘上缺失;反向代理返回 502/503/504 |
internal |
500 | -32603 | 服务端内部错误 |
响应没有错误正文时(例如被代理拦截),SDK 按 HTTP 状态反推错误码:400→invalid_argument、401→unauthorized、403→forbidden、404→not_found、409→conflict、413→too_large、502/503/504→unavailable,其他→internal。
JSON-RPC 协议本身的错误另有 -32700(解析失败)、-32600(请求无效)、-32601(方法不存在)。
客户端该怎么做
invalid_argument(400)
请求本身有问题,重试不会成功。检查参数:应用 id、平台名、渠道名是否符合命名规则,versionCode 是否是整数。
SDK 在验签失败(签名不是来自内置的任何公钥)或 manifest 不是你请求的 app/platform/channel 时也会报这个错误码。这时不要安装,检查应用里内置的公钥是否与 relhub keys 一致;服务端做过密钥轮换的话,应用需要同时内置新旧公钥。
unauthorized(401)
只会出现在写接口上(读接口会忽略无效 token)。检查 Authorization: Bearer <token> 是否带上、token 是否被吊销。不要自动重试。
forbidden(403)
token 有效,但无权做这件事:应用 token 操作了别的应用,或调用了只有管理员能用的接口(建应用、签发 token、下架/上架、不带 app 的统计)。换用正确的 token,不要重试。
app_delisted(403)
消息形如:
应用 "nightdesk" 已下架,请联系管理员上架
管理员把这个应用下架了(见 管理面板)。对匿名请求,应用详情、检查更新、watch、latest、版本列表/详情和下载都会返回这个错误。
客户端应当:
- 不要循环重试,也不要缩短检查间隔。这不是临时故障,在管理员上架之前每次都会得到同样的结果;
- 把服务端返回的
message原样展示给用户(它已经是中文提示),而不是显示成「网络错误」或「没有更新」; - 保持当前已安装的版本正常运行,按平常的周期(例如下次启动或几小时后)再检查一次即可;
- 正在进行的
watch长轮询循环收到它应当停止,而不是立刻再发起。
Go SDK 用 apiErr.Code == "app_delisted" 判断,C# SDK 用 e.Code == "app_delisted" 判断。
not_found(404)
- 检查更新时:渠道上还没有发布任何版本,或应用 / 平台 id 写错了。对已上线的客户端来说,通常当作「没有更新」处理,按正常周期再查;
- 下载时:这个版本已被撤回。重新调用
check拿到当前提供的版本; - 基础地址配错(少了反向代理的路径前缀)也会表现为 404,第一次接入时先用
GET /v1/info确认地址。
conflict(409)
发布端的错误,客户端检查更新不会遇到。
- 发布时:versionCode 没有比该平台曾经发布过的最大值更大(包括已撤回的)。不要重试同一个 versionCode;如果是流水线重跑,先查这个版本是否已经发布成功;
- 撤回时:这个版本还被某个渠道提供,先 promote 渠道到别的版本;
- promote 时:目标版本已被撤回,需要先
unyank。
too_large(413)
安装包超过服务端上限。缩小产物,或请管理员调大上限(RELHUB_MAX_SIZE)。
unavailable(503)
临时问题,可以重试,但要指数退避(例如 1 秒、2 秒、4 秒……上限几分钟),不要紧密循环。Go / C# SDK 的 Download 和 WatchLoop 已经内置了重试;单次的 Check 由你决定。如果配置了备用服务器,SDK 会自动换下一台。
internal(500)
服务端错误。按 unavailable 的方式退避重试几次;持续出现请把 message 和时间报告给服务端管理员。C# SDK 收到读不懂的响应(例如被登录页拦截返回了 HTML)也会报这个错误码,这种情况通常是基础地址或代理配置不对。
不是服务端错误码的情况
- 校验失败:下载的文件大小或 SHA-256 与 manifest 不符。Go SDK 返回
relclient.ErrChecksum,C# SDK 抛ChecksumException。丢弃文件,重新下载; - 网络错误 / 超时:按
unavailable处理; 204 No Content:watch长轮询在等待时间内没有新版本,这不是错误,直接再调一次watch。