跳至主要内容

HTTP 錯誤處理

訂閱 onSseError 來處理 bot provider 回傳的 HTTP 錯誤。搭配 @asgard-js/core 的 isHttpError helper，可以安全地檢查 status code。

HTTP 429 用量限制

點擊下方按鈕模擬 onSseError 收到 HTTP 429 錯誤。handler 會呼叫 isHttpError() 判斷錯誤類型，然後顯示 toast 通知。下方的程式碼展示實際的接線方式。

程式範例​

import { isHttpError } from "@asgard-js/core";

<Chatbot
  onSseError={(error) => {
    if (isHttpError(error) && error.status === 429) {
      toast.warning("用量已達上限，請稍後再試");
    }
  }}
  {...rest}
/>;

HttpError​

屬性型別說明
statusnumberHTTP 狀態碼（如 401、403、429、500）
statusTextstring狀態文字
bodyunknown回應 body

isHttpError(error) 是 type guard，確認 error 是 HttpError 後才安全存取上述屬性。

常見錯誤碼​

狀態碼場景
401API key 無效或過期
403無權限存取此 bot provider
429請求頻率超過限制
500Bot provider 內部錯誤

錯誤泡泡與 details 展開​

asgard.run.error 會在對話串裡留下一顆錯誤泡泡。它原樣顯示後端給的 message——sandbox 被 配額或訂閱狀態擋下時，理由就只寫在那裡，換成固定字串等於把使用者唯一的線索丟掉。事件沒帶 message 時才退回「發生未預期的錯誤」。

其餘屬於診斷而非指示的欄位（code、traceId、上游的 inner）收在「顯示更多／顯示較少」 的展開區裡，整包 { traceId, ...error } 直接 JSON.stringify 印出來：

  • 整包印是刻意的。這個 payload 的形狀還在變（後端仍在補 code / inner），手挑欄位會在 它下次新增時安靜地漏掉；整包印也讓工程師有一塊可以直接貼進 ticket 的東西。
  • 除了 message 以外真的有東西時才會出現切換鈕——否則展開後看到的就是上面那行摘要。
  • 後端錯誤可以任意長，所以摘要夾到兩行、展開區各自有高度上限並在裡面捲動；泡泡的佔位始終有界。

errorMessageRenderer 仍然優先：有回傳值就整顆換成你的，回傳 null / undefined 則落回上述 預設 UI，不會把泡泡清空。

展開區的顏色可以覆寫，見主題的 JSON 與錯誤細節變數。

深入閱讀​

底層的訊息 API 與錯誤回傳定義，見 Asgard 開發者文件：