release-publish

错误码

所有接口出错时都返回统一的结构。

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。