群益API 下單回傳 980 怎麼讀？4 碼錯誤碼與交易主機退單訊息的差別

下單回傳 980，拿去錯誤代碼表查不到。log 裡只記了回傳的數字，事後不知道為什麼被退單。非同步下單時，OnAsyncOrder 的 nCode 不是 0，也不知道原因在哪裡。

群益API 下單失敗有兩種來源，官方說明本身就是這樣分的：4 碼的回傳值是群益元件的錯誤碼，查代碼定義表；其他值由交易主機回傳，原因寫在訊息字串裡。

本文講的是下單函式的回傳值。委託回報字串第 0 欄出現的 980，處理方式見〈群益API 委託回報怎麼解析〉。

群益API 下單失敗的兩種來源

官方在下單函式 SendFutureOrderCLR 的回傳值說明裡寫：

• 「0表示成功，其餘非0數值都表示失敗。」
• 「當錯誤代碼為4碼時，可參考6代碼定義表，所屬委託物件亦有欄位值說明供參。」
• 「其他錯誤則由「交易主機」回傳錯誤代碼及錯誤原因。」

整理成一張表：

回傳 0 的意思，見〈群益API 下單回傳值是 0 就成功了嗎〉。這跟〈群益API 註冊失敗怎麼處理〉講的是同一個道理：錯誤碼分屬不同的系統，查對地方才查得到。

失敗原因在哪裡？同步看 bstrMessage，非同步看 OnAsyncOrder

同步委託：

Long SendFutureOrderCLR([in] BSTR bstrLogInID, [in] VARIANT_BOOL bAsyncOrder, [in] struct FUTUREORDER* pAsyncOrder,[out] BSTR* bstrMessage);

依官方說明，同步委託回傳 0 時，訊息內容是 13 碼的委託序號；回傳非 0 時，訊息內容是失敗原因。在 Python 裡，comtypes 會把 [out] 參數 bstrMessage 一起放進回傳值，所以要拆開來看。

非同步委託：結果從 OnAsyncOrder 事件回來。

void OnAsyncOrder([in] LONG nThreadID,  [in] LONG nCode, [in] BSTR bstrMessage  );

官方的說明是（節錄）：

• 「委託成功：收單回傳訊息為 委託序號」
• 「委託失敗：收單回傳訊息為 委託失敗原因」
• 「送單函式中使用非同步下單時會取得一個Thread ID，當此事件觸發時可藉由nThreadID對應下單來源。」

不管同步還是非同步，失敗時都要把訊息字串原樣記下來，因為回傳的數字本身不說明原因。

我們觀察到的交易主機退單：980 加方括號原因碼

以下是我們的觀察，共兩次（2026-09-09），不是官方記載：

• 被交易主機退單時，同步呼叫的回傳值是 980。
• 訊息字串開頭是方括號包起來的原因碼，後面接中文原因。

其中一次是用交易所代碼 TXFI6 下單，回傳 980，訊息是（節錄）「[400] DB查詢失敗……TXFI6無法轉換商品ID」。商品代碼為什麼要用 TX09 這類代碼，見〈群益API 商品代碼怎麼填〉。

另一次是帳戶側的條件不符，回傳值同樣是 980。

要注意三件事：

• 我們只觀察到 980。官方沒有逐一列出交易主機會回哪些碼，所以本文不說「980 一定代表交易主機退單」。
• 方括號原因碼代表什麼，官方沒有提供清單，本文也不做對照表。
• 委託回報字串第 0 欄也會看到 980 開頭的資料。兩處的 980 是不是同一件事，官方沒有說明，我們也沒有對照過。回報那邊的處理方式見〈群益API 委託回報怎麼解析〉。

退單原因分兩類：程式能修的、帳戶側的

官方沒有給原因碼的分類規則。下面這個二分法，是我們為了教學做的，判斷方式是看訊息文字：

帳戶側的原因，如果有遇到這類的問題可以先跟您的營業員反應。

群益API 下單失敗時，log 要記什麼？

• 回傳值：數字本身。
• 訊息字串原文：不要截斷，也不要翻譯後才記。
• 當時的委託內容：商品代碼、價格、數量。
• 非同步下單：記下 nThreadID，用它對回是哪一筆委託。

群益API 下單回傳值判讀程式碼

下面的片段判斷回傳值屬於哪一類，再把訊息原樣記下。片段不含真實的下單參數，委託物件的價格與時效欄位怎麼填，見〈群益API 下單價格為什麼是字串〉：

# 群益API 下單回傳值判讀：4 碼查元件錯誤碼表，其他值看交易主機的訊息
import logging

log = logging.getLogger("order")


def send_and_check(order_lib, center, login_id, order_obj):
    # False：同步委託；comtypes 把 [out] 的 bstrMessage 和回傳碼一起回傳：（訊息, 回傳碼）
    message, code = order_lib.SendFutureOrderCLR(login_id, False, order_obj)
    code = int(code)

    if code == 0:
        log.info("送出成功，委託序號 %s；結果請看回報", message)
    elif len(str(abs(code))) == 4:
        log.error("元件錯誤碼 %s：%s（訊息：%s）", code,
                  center.SKCenterLib_GetReturnCodeMessage(code), message)
    else:
        log.error("非 4 碼回傳 %s，原因：%s", code, message)   # 原樣記下，不截斷
    return code, message

幾點說明：

• 回傳形態：comtypes 把 [out] 的 bstrMessage 和回傳碼一起回傳，順序是（訊息, 回傳碼），所以直接拆成兩個變數。參數方向怎麼決定回傳值，見〈群益API Python 回傳值為什麼是 list〉。
• 4 碼的判斷依官方「錯誤代碼為4碼時」的說法。非 4 碼的分支，log 只寫「非 4 碼回傳」，不寫成「交易主機回傳」。
• 4 碼的分支也記下訊息字串，原因同上一節。
• 片段不印帳號；order_obj 由你依自己的委託內容填寫。
• 非同步下單：在 OnAsyncOrder(self, nThreadID, nCode, bstrMessage) 裡做同樣的分類，並用 nThreadID 對回委託。

群益API 下單失敗的 4 個誤解

1. 誤解： 下單回傳的錯誤碼都能在錯誤代碼表查到。其實： 官方說明 4 碼的才查代碼定義表；其他錯誤由交易主機回傳，原因寫在訊息字串裡。
2. 誤解： 記下回傳的數字就夠了。其實： 失敗原因在 bstrMessage（或 OnAsyncOrder 的訊息）裡，數字本身不說明原因。
3. 誤解： 每一種退單原因都能靠改程式解決。其實： 有些是帳戶側的條件，程式改不了。
4. 誤解： 非同步下單沒有錯誤訊息。其實： 結果從 OnAsyncOrder 回來，失敗時訊息就是失敗原因。

常見問題

風險揭露

期貨與選擇權屬高槓桿商品，價格波動可能造成超過原始保證金的損失，交易人須自負交易責任。本文為程式開發技術教學，說明群益API 下單失敗時回傳值與訊息的判讀方式，不構成投資建議，也不保證任何交易結果。程式化交易並不降低市場風險，下單失敗若未被程式正確辨識與記錄，可能讓你誤判委託狀態，正式使用前請充分測試。

投資人教育資源

延伸閱讀

• 〈群益API 下單回傳值是 0 就成功了嗎〉——回傳 0 只代表送出，結果看回報。
• 〈群益API 委託回報怎麼解析〉——回報字串第 0 欄是 980 時的處理方式。
• 〈群益API 登入錯誤怎麼判讀〉——群益錯誤碼的分類方式。
• 〈群益API 商品代碼怎麼填〉——用交易所代碼下單會被退單的原因。

參考資料

• 下單回傳值的說明（4 碼查代碼定義表、其他由交易主機回傳）、bstrMessage 的內容、OnAsyncOrder 的說明與 nThreadID，依群益官方元件說明文件。
• 交易主機退單時回傳 980、訊息開頭為方括號原因碼：我們 2026-09-09 的兩次觀察，非官方文件記載。
• 退單原因的兩類分法：我們為了教學整理的分法，非官方分類。

免責聲明

本文章僅作為群益API實作經驗分享，不構成投資建議，且策略及程式皆應自行撰寫。期貨及衍生性金融商品交易屬高風險投資，請謹慎評估自身風險承擔能力。