错误与排障

协议错误体复制标题链接

/v1/oauth/** 与 /v1/oidc/** 的失败响应恒为两键，不套 v1 信封：

{ "error": "invalid_client", "error_description": "Unknown or inactive OAuth client" }

同意页 / 内嵌的拒绝理由复制标题链接

内嵌模式（/oauth/embed）在渲染前就做完预校验，失败会以 deny= 回给页面，页面再把理由 postMessage 给宿主：

JS SDK 侧的错误码（not_configured / popup_blocked / timeout …）见前端接入。

业务接口状态码复制标题链接

/v1/** 的错误体是信封：

{
  "code": "auth.unauthenticated",
  "message": "Authentication is required",
  "data": null,
  "requestId": "req_…"
}

游戏面的四个专属业务码复制标题链接

/v1/games/** 的权限收紧带来四个新码。它们都会出现在公开的 GET /v1/catalog/codes 里，所以文案里不含任何阈值或判定细节 —— 也别试图从文案反推规则。

game.firstPartyOnly 只出现在仅第一方开放的形状上（以及第三方打 /v0 面时， 曲目别名与谱面评论两族除外）。完整清单见权限范围与可用 API。

428 的 data 形状：

{
  "code": "game.writeConfirmationRequired",
  "message": "该写入需要用户确认后重试",
  "data": {
    "confirmation": {
      "confirmationToken": "wc_7Q2…",
      "approveUrl": "rankhub://write-confirmation?token=wc_…",
      "expiresAt": "2026-10-22T19:10:00Z"
    }
  },
  "requestId": "req_…"
}

重放细节（一次性、30 分钟、payload 变了就 409 common.conflict）见 成绩读取与写入。

删除申请的成功码：common.accepted复制标题链接

删除申请成功返回 202 + code: "common.accepted"（"已接受"）。 别把它当成失败：它表示"申请已受理，等用户处理"，data 里有 requestId 与 expiresAt。

限流码复制标题链接

限流命中的错误信封是 429 + code: "common.rateLimited"（retryable: true）， 并带 Retry-After（秒）。按它退避（带抖动）；单批条数超限是 400 common.invalidArgument， 不是限流。详见业务 API 总览。

按症状查复制标题链接

上报问题要带什么复制标题链接

• 出问题的接口（哪个 URL、哪个步骤）；
• 时间（精确到分钟，带时区）；
• 响应里的 X-Request-ID（或在信封里的 requestId）—— 服务端日志按它索引；
• error / error_description 原文；
• 不要贴 access_token / refresh_token / client_secret / 授权码 / DPoP proof。

服务端日志只记录 requestId、主体哈希、jkt 哈希，不会记录令牌、proof、nonce 或验证码。