OpenMax
免费试用

错误与会话过期

处理请求失败、发送失败、令牌过期和渲染错误。

错误与会话过期

错误提示

操作失败时,聊天通过宿主的 attention 能力上报错误。默认实现不显示任何内容,需要接到你的 toast 组件上:

import { createChatHost } from "@openmaxai/chat-openmax/react";

const host = createChatHost({
  baseUrl: "https://openmax.com",
  wsUrl: "wss://openmax.com/ws",
  auth: { mode: "token", getToken },
  ports: {
    attention: {
      notify: (level, message) => toast[level](message), // 你的 toast 库
      setUnreadSignal: (count) => setTitleBadge(count),
    },
  },
});

上面是接 OpenMax 的一行写法,连接那几项见接入 OpenMax。接自己的后台时用 @openmaxai/chat-sdk/react 的 createChatHost({ adapter, ports }),ports 写法相同。自定义宿主则把同样的对象传给 createLocalPorts 的 ports。

发送失败

失败的消息留在消息区,标记「发送失败」:

  • 重试:用相同的 id 和内容重发;失败在上传环节时,先重新上传同一批文件。
  • 删除:只在本地移除。

服务端内容过滤拦下消息时,发送能力应返回 { blocked: { refusalText } } 而不是抛错。消息会保留并附带说明和删除按钮,不提供重试。

卡片按钮的错误显示在卡片里,见交互卡片。

SDK 错误类型

错误 何时出现 从哪引入
ChatSdkConfigError createChatHost 的构造参数不合法时同步抛出(例如接 OpenMax 时缺 baseUrl、既没有 wsUrl 也没有 realtime: "off"、auth.mode 不支持) @openmaxai/chat-sdk
ChatSdkError 适配器的调用失败,带种类 kind、retryable,以及后端的 status、code @openmaxai/chat-sdk
ChatSdkRequestError OpenMax 的 REST 请求失败;ChatSdkError 的子类,kind 由 HTTP 状态推出 @openmaxai/chat-openmax

种类、字段和判别函数 isChatSdkError 见 @openmaxai/chat-sdk · 错误;OpenMax 的状态码怎么推出种类、getToken() 失败时的 code("token_unavailable")、还不是 ChatSdkRequestError 的两种情况,见 @openmaxai/chat-openmax · 错误。message 是给用户看的一句话:组件原样提示非空的 message;为空串时用组件自己的文案(建群等群管理写操作按 kind 取,其余用这次操作的兜底句)。@openmaxai/chat-openmax 只在认得后端 code 时给出这句话,后端原文只在 cause 里。

useChatSdkConversationList() 返回最近一次的 error 和 refetch,可用来给会话列表加提示和重试。这个 error、以及 host.openConversation 失败时的 error 一定是 ChatSdkError:适配器抛的不是它时,SDK 经 toChatSdkError 换成它(断网的 TypeError 为 network,AbortError 为 cancelled,TimeoutError 为 timeout,其余为 unknown),原错误在 cause。只有这两处;MessageThreadNext 内部读消息的错误仍是原样的。换法见 @openmaxai/chat-sdk · 错误 · toChatSdkError。

统一错误

按种类给自己的界面分支时,用 isChatSdkError 判,不要用 instanceof;别处接到的错误也想按种类处理,先用 toChatSdkError 换一下:

import { isChatSdkError } from "@openmaxai/chat-sdk";

function describe(error: unknown) {
  if (isChatSdkError(error) && error.kind === "network") return "网络连接失败";
  return "出错了";
}

会话过期

SDK 不会自行刷新令牌,流程如下:

  1. 第一个需要令牌的请求调用 getToken(),结果缓存。
  2. 遇到 401 再调一次 getToken({ refresh: true })(这时要真去续期),用新令牌重发一次。同时(或先后)被拒的多个请求只续一次。getToken 回 { token, expiresAt } 时,令牌在到期前就续,且只有 code 为 AUTH_TOKEN_EXPIRED 的 401 才续;其它 401 不续,直接走第 3 步(见接入 OpenMax · 令牌与过期)。
  3. 重试后仍是 401,请求以 ChatSdkRequestError(status: 401)失败。
  4. WebSocket 用同一令牌换一次性票据,换票遇 401 同样先续期、再换一次。续期后仍被拒或 getToken() 以凭据失效失败,就不再重连;连接被服务端以凭据失效关闭(如个人 API Key 被吊销)也不再重连,同样算会话过期。用户重新登录后请新建 host。换票遇 403(凭据有效但不许换票,如个人 API Key 没勾对应权限)也不再重连,但不续期、不算会话过期。
  5. 续期接口断网、超时时凭据可能还好:getToken() 抛 kind 为 network 的 ChatSdkError,请求就以 network 失败,不算会话过期,实时照常退避重连,下一次 401 再续。抛普通 Error 或返回空串才是 unauthorized。

所以续期和跳转登录都放在 getToken() 里:

import { ChatSdkError } from "@openmaxai/chat-sdk";
import { createChatHost } from "@openmaxai/chat-openmax/react";

const host = createChatHost({
  baseUrl: "https://openmax.com",
  wsUrl: "wss://openmax.com/ws",
  auth: {
    mode: "token",
    getToken: async ({ refresh } = {}) => {
      // refresh 为 true:手上那张刚被 401 拒了,要真去续期
      let token;
      try {
        token = refresh ? await session.renew() : await session.getFreshToken();
      } catch (e) {
        // 续期接口不可达:凭据可能还好,报 network(不算会话过期,下一次 401 再续)
        if (isNetworkFailure(e)) throw new ChatSdkError("network", "renew failed", { cause: e });
        throw e;
      }
      if (!token) {
        redirectToLogin();
        throw new Error("signed out");
      }
      return token;
    },
  },
});

续期失败(续不出令牌、或重发仍是 401)、或换票续期后仍被拒时(续期因网络没成不算,见第 5 条),SDK 经 attention.notify("error", …) 提示一次「登录已过期」,同时失败的几个请求只提示一次。上面的一行配置不收 onUnauthorized(已知缺口);要在这时跳转登录,改用 createChatHost({ adapter: createOpenMaxAdapter(config), onUnauthorized }),回调同样只调一次,见错误模型 · onUnauthorized。

身份相关请求(个人信息、会话成员)失败后 5 秒内不重试。个人信息加载前,自己发的消息会显示成别人的,加载后自动纠正。

渲染错误

规划中

聊天的每个区域自带一层错误边界:一个区域渲染时抛错,只有它换成兜底界面,其余区域照常,页面不会白屏。你不用自己包。

区域(ChatRenderErrorArea) 包住什么 兜底界面 自动复位
conversation-list ConversationList 「这部分暂时无法显示」和「重试」 —
header ChatHeader 同上 换会话时
message-thread 消息列表,不含输入框 同上 换会话时
message 一条消息 气泡的位置显示「这条消息无法显示」,没有重试;同一会话的其他消息照常 这条消息的 content_version 变了时
composer 输入框 「这部分暂时无法显示」和「重试」;草稿已经存进 drafts,重试后恢复 换会话时
info-panel ChatInfoPanel 同 conversation-list 换会话时
agent-runs AgentRunList、AgentRunPanel 同 conversation-list 换 Agent 时
  • 重试是把这个区域重新挂载一次,仓库里已有的数据不重新请求。
  • 只接住渲染时的错误。 点击、发送等操作的失败不经错误边界,照常走错误提示和各操作自己的回滚。
  • 缺能力的抛错也接住(下一节),兜底界面相同;开发构建里另在控制台说明缺了哪项能力。
  • 焦点: 出错时焦点在这个区域里的,移到「重试」按钮上;不在的,焦点不动。
  • 你在外面再包一层自己的错误边界也可以,内置的先接住。

上报和自定义

src/app.tsx

<ChatProvider
  host={host}
  onRenderError={(error, { area, conversationId }) => {
    reportError(error, { tags: { chatArea: area, conversationId } });
  }}
  renderErrorFallback={({ area, retry }) =>
    area === "conversation-list" ? <MyListFallback onRetry={retry} /> : null
  }
>
  {children}
</ChatProvider>
ChatProvider 属性 类型 说明
onRenderError (error: unknown, info: { area: ChatRenderErrorArea; conversationId?: string }) => void 任一区域接住错误时调用一次,用来上报。不要在里面抛错
renderErrorFallback (props: { area: ChatRenderErrorArea; error: unknown; retry: () => void }) => ReactNode 换掉默认兜底界面。返回 null 用默认的。message 区域没有 retry,调用无效

兜底文案在 chat 命名空间:renderError.area(「这部分暂时无法显示」)、renderError.retry(「重试」)、renderError.message(「这条消息无法显示」)。

一定会抛的情况

下面这些是用法错误,渲染时直接抛,由上面的错误边界接住(错误信息指明缺什么):

  • 渲染 ConversationList 但没有 conversations 能力。
  • 渲染 CreateGroupModal / ChatInfoPanel 但没有 groupManagement 能力。
  • 聊天组件不在 ChatProvider 里。这一条错误边界接不住:边界本身在 ChatProvider 里,所以会冒到你的应用。

先修原因,见能力。