Response and Error Handling

回應與錯誤處理

呼叫端必須同時檢查 MCP transport 層與業務層。HTTP 200、MCP result 存在或 tool call 沒拋例外，都不代表富邦業務請求成功。

標準業務回應

{
  "status": "success",
  "data": {},
  "message": "成功訊息"
}

{
  "status": "error",
  "data": null,
  "message": "可供使用者或程式判斷的原因"
}

部分歷史行情錯誤的 data 為空陣列；部分較舊交易分支可能沒有明示 data。Client 應以 status 為首要 business discriminator，而不是以 data truthiness 判斷。

MCP structured output

在 MCP v2 client 中，dict 回應會出現在 structured content。正確判斷順序：

1. transport／JSON-RPC 是否成功。
2. MCP tool result 是否為 error。
3. structuredContent.status 是否為 success。
4. data 是否符合該 tool 的業務預期。

資料不足

唯讀量化工具使用：

{
  "status": "error",
  "data": null,
  "message": "insufficient_data: 商品共同交易日不足..."
}

這不是可用零值取代的數值錯誤。應將缺少的來源、日期範圍與觀測數呈現給使用者。

常見錯誤類型

類型	判斷	建議處理
設定錯誤	啟動前缺少 env、port／boolean 無效	修正設定後重啟
認證錯誤	login 失敗、帳戶未初始化	檢查登入方式、PFX 與帳戶，不進行寫入
參數錯誤	Pydantic／enum／日期／數量驗證失敗	修正輸入，不重試相同 payload
業務錯誤	SDK is_success=false 或 REST error envelope	保留券商 message，依語意決定
資料不足	insufficient_data:	增加正式資料或縮小分析，禁止補假資料
流量控管	message 含券商流量控管訊息	唯讀查詢採 bounded backoff；寫入先回讀
連線錯誤	timeout／connection reset	查 callback 與券商查詢；寫入視為 outcome unknown

寫入逾時處理

flowchart TD
    W[WRITE tool timeout] --> U[標記 outcome_unknown]
    U --> Q[查 get_order_results_detail]
    Q --> F[查 filled reports or history]
    F --> C{是否已建立或成交}
    C -->|是| R[依券商狀態處理，不重送]
    C -->|否且已確認| D[由人員決定是否重新送出]
    C -->|仍不明| H[停止自動化並人工處理]

Loading

不要讓 generic retry middleware 自動包住交易寫入。相同 payload 重送可能建立重複委託。

記錄與隱私

建議記錄：tool name、correlation ID、時間、business status、券商 order／condition identifiers、資料日期。不要記錄：密碼、API Key、PFX 內容、完整帳戶身分資料或未遮罩的敏感 payload。

正規化注意事項

• 日期／時間 object 會正規化成 ISO 字串。
• enum 通常轉為 member name。
• REST 股務事件保留官方欄位大小寫。
• 空 list 可能代表真的沒有資料，也可能是 endpoint error 分支；一律同時檢查 status 與 message。