OpenMax
免费试用

错误

ChatSdkRequestError:OpenMax 的 HTTP 状态怎么映射成 ChatSdkError 的种类,401 时怎么续期。

错误

OpenMax 适配器失败时抛什么、种类怎么来。错误种类各是什么意思、界面怎么处理、onUnauthorized 什么时候调,见 @openmaxai/chat-sdk · 错误;本页只写 OpenMax 这一侧的映射。

ChatSdkRequestError

class ChatSdkRequestError extends ChatSdkError {
  readonly status: number;
  readonly field?: string;
  constructor(status: number, message: string, code?: string, options: {
    kind?: ChatSdkErrorKind;
    cause?: unknown;
    field?: string;
  } = {});
}

一次 REST 请求失败。它是 ChatSdkError 的子类,isChatSdkError() 认得它,组件和你的代码按 kind 分支即可。

字段 说明
status HTTP 状态码;0 表示没拿到完整响应(断网、跨源被拦、请求被中止或超时,或取令牌失败;响应头到了、正文没读完时出这几种情况也是 0)
message 给用户看的一句话,界面原样显示:后端错误体里的 code 认得时,是 SDK 错误码表里那一句(语言按 locale);认不得的 code、没有 code(含没拿到响应、取令牌失败)、或那句话要插值而后端没给值时是空串,组件按 kind 取自己的文案。建群(POST /api/v1/conversations/groups)收到 403 AUTH_ORG_MEMBERSHIP_REQUIRED 时是另一句中性的话「部分成员已不在组织中,或你没有权限」:选中的成员 id 无效(已软删,如被拆除的平台 Agent;别的组织的成员;不存在的 id)时后端回的也是这个码,与「你自己已不在组织」分不出;别的请求收到它仍是表里原来那一句。后端的 detail / title 原文不进这里
code 后端错误体里的稳定码,有才给;取令牌失败时是 "token_unavailable"
kind 由状态推出,见下表;构造时第 4 个参数可以指定别的种类
cause 原始错误,有才给。后端回了错误体时就是那个错误体(detail / title 原文在里面);没拿到响应时是 fetch 或 getToken 抛的那个值
field 后端错误体里的字段路径(如表单卡的 answers.<key>.text),有才给

后端的两种错误形状都认:嵌套的 { error: { … } } 和顶层的 { detail, title, code }。

状态到种类

情况 kind
401 unauthorized(已经续过一次令牌、重发过一次,见续期)
403 forbidden
404、410 not_found
409 conflict
400、413、422 validation
429 rate_limited
408 timeout
502、503、504 unavailable
其他 5xx server
status 为 0:断网、DNS、跨源被拦(fetch 抛 TypeError) network
status 为 0:请求被 signal 中止(AbortError,或调用方自己给的任意中止原因,如 abort("navigated");响应头之前与读正文时同一个判法) cancelled
status 为 0:AbortSignal.timeout() 到时(TimeoutError) timeout
取令牌失败(code 为 "token_unavailable") 按 getToken 抛的东西定,见 OpenMaxGetTokenOptions
撤回、编辑、表态被 412 或 403 拒绝 forbidden(isChatOperationNotAllowed() 认得,界面提示「无法撤回 / 无法编辑」)
表里没有的状态码 unknown

续期

遇到 401,适配器先调 getToken({ refresh: true })(这时要真去续期,不要把缓存里那张原样交回),用新令牌把那一发重发一次;续不出令牌、或重发仍是 401 才以 unauthorized 失败。同时(或先后)被拒的几个请求只续一次。实时换票走同一条路:续期成功就再换一次票、照常建连。

getToken 回的是 OpenMaxToken({ token, expiresAt })时,令牌在到期前就续,且只有 code 为 AUTH_TOKEN_EXPIRED 的 401 才续、才重发;其它 401(令牌或 Key 被吊销)当场以 unauthorized 失败。

续期因网络没成(getToken 抛 kind 为 network 的 ChatSdkError)不算凭据失效:那次调用以 network 失败,不调 onUnauthorized,实时照常退避重连,下一次 401 再续。

凭据失效时:失败的调用抛 kind 为 unauthorized 的 ChatSdkRequestError,实时停止重连并经 sink.error 报一次;{ adapter } 写法给了 onUnauthorized 就调它,一行写法(不收 onUnauthorized)由 SDK 经 attention.notify 提示一次「登录已过期」。见 @openmaxai/chat-sdk · 凭据失效。实时连接被服务端以凭据失效关闭码关闭时同样按凭据失效处理一次。

换票被拒(403,kind 为 forbidden)时实时也停止重连、经 sink.error 报一次,但这不是凭据失效:不续期、不调 onUnauthorized、不提示「登录已过期」。实时不会自己恢复:给 Key 补上权限后,要新建宿主(或刷新页面)才会重新连上。

还不是 ChatSdkRequestError 的

  • 响应头已到、读响应体途中连接断开:抛原样的 TypeError,没有 kind。
  • 上传的 PUT 失败、断网、被取消:抛普通 Error。上传前后的 prepare、finalize 两个请求失败仍是 ChatSdkRequestError。
  • 在会话面外上传(没有会话 id):抛普通 Error。

这几种用 isChatSdkError() 判会是假。