群益API 連線狀態碼怎麼解讀？3001 與 3003 的差別與就緒判定

群益API 連線狀態回報了 3001，看起來已經連上，你的程式馬上送出訂閱。但依官方文件，這時候還不到可以訂閱的時間點。

3001 只代表連上線了，還不代表可以訂閱。 連上線和可以訂閱，是兩個不同的事件。

群益API 連線狀態 3001 和 3003 差在哪？連上線不等於可以訂閱

呼叫 SKQuoteLib_EnterMonitorLONG 之後，群益API 連線狀態由 OnConnection(nKind, nCode) 事件回報。官方錯誤代碼表對這兩個代碼的定義是：

官方在 OnConnection 的參數說明裡，把 3003 講得更白（節錄）：

SK_SUBJECT_CONNECTION_STOCKS_READY 表示為商品基本資料已下載完成。

3001 只代表連上了；3003 才代表商品資料下載完成。 而訂閱要等的是後者——官方在三個函式的備註裡各寫了一次（皆為節錄）：

訂閱報價、訂閱成交明細與五檔、查詢商品檔，三件事都要等 3003。 〈群益API 報價訂閱有哪兩層〉講的兩層訂閱，前提就是這個事件。

如果你讀過〈群益API 下單初始化有哪 7 步〉會覺得眼熟：回報通道 ConnectByID 之後，要等 OnComplete 才開放送單。這裡是同一個形狀：連上線之後還有一段準備期，準備完成後，另有一個事件通知。

可以在 OnConnection 事件裡直接訂閱嗎？

不建議。官方 OnConnection 的備註全文是：

避免在此處直接進行EnterMonitorLONG、LeaveMonitor、RequestStocks and RequestTicks 等報價連線、斷線、訂閱，若全市場商品未下載完成，即無法進行商品訂閱。

所以正確的分工是：事件裡只記下狀態（例如把一個「報價就緒」旗標翻開），訂閱動作放到事件之外去做。

這也符合回呼的一般紀律——回呼裡只做最輕量的收集。〈群益API 事件回呼跑在哪個執行緒〉列過一個在 OnConnection 回呼裡呼叫查詢函式的實際案例，可以對照著看。

群益API 連線狀態有哪些代碼？哪些算斷線

OnConnection 的 nKind 不只 3001、3003。官方參數說明另有一句「其他錯誤代碼，可參考代碼定義表」，所以下面這張表不是完整清單，而是官方錯誤代碼表中與連線有關的幾個（這幾個是我們挑的，官方沒有這個分類）：

⚠️ 3004、3005 在官方表裡沒有說明文字。不要從常數名去猜它們的意思——猜出來的意思聽起來會很合理，但那不是官方說的。

另一個參數 nCode，官方說明是「代碼為0值即表示執行正確，非0表示例外事件」。

官方另有一個查詢函式 SKQuoteLib_IsConnected，回傳值的說明是「0表示斷線。1表示連線中。2表示下載中。」，備註寫「請同時接收通知事件OnConnection」。官方沒有說明這三個值和 3001、3003 怎麼對應，所以就緒判定仍以 OnConnection 的 3003 為準。

哪些算斷線，是程式自己的分類

實務上需要一個「報價就緒」旗標：只由 3003 翻開；收到斷線類事件時關上，之後重新等 3003。

哪些代碼算「斷線類」，官方沒有分類，是程式自己決定的。我們的實作把 3002、3021、3033 當成斷線處理——這是我們的選擇，你可以依自己的需求調整。

海外報價也等 3003 嗎？OnConnect 和 OnConnection 不一樣

不一樣。海期報價 SKOSQuoteLib 的連線事件是 OnConnect，不是 OnConnection，參數順序也不同：

國內  void OnConnection([in] LONG nKind, [in] LONG nCode);
海期  void OnConnect([in] LONG nCode, [in] LONG nSocketCode);

有三個差異要注意：

1. 事件名不同：OnConnection 與 OnConnect。
2. 狀態碼放的參數不同：國內的狀態碼放在第一個參數 nKind，海期的狀態碼放在第一個參數 nCode。兩邊都有一個叫 nCode 的參數，但意思不一樣。
3. 官方參數說明沒有列 3003：海期 OnConnect 的 nCode 說明列的是連線（節錄：「SK_SUBJECT_CONNECTION_CONNECTED 表示為連線事件。(3001)」）與斷線事件，沒有 STOCKS_READY。

從實務經驗來說，我們在海期報價 SKOSQuoteLib 上實測，海期不會送出 3003。拿國內的 3003 當就緒條件，海期程式會永遠等不到。海期報價用 OnConnect 的 3001 判定連線。

3003 要等多久？等待時要注意的兩件事

從 EnterMonitorLONG 到收到 3003 需要一段時間。我們的紀錄裡，出現過超過 20 秒的情況。

這帶出兩件事：

第一，等 3003 要設逾時。 時間到了就走重新連線的流程，不要無限等待。逾時設多長，要看你自己的環境，本文不給數字。

第二，等待期間不要再呼叫一次 EnterMonitorLONG。 我們觀察過一次：握手還沒完成就又呼叫了一次 EnterMonitorLONG，那一次連線之後，我們觀察的那一檔商品即使重送成交明細訂閱多次，都收不到成交明細與五檔。這是單一場次、單一商品的觀察，我們不把它寫成必然會發生；但結論很清楚——逾時要設得夠長，等待期間不要重複連線。

群益API 連線狀態就緒之後：收盤後的 keep-alive

連線就緒不代表可以放著不管。官方在 SKQuoteLib_RequestServerTime 的注意事項裡說明了原因：收盤後沒有報價資料傳送時，連線可能被防火牆切斷。而官方給的做法是（節錄）：

請固定每十五秒呼叫此函式，確保連線正常。

RequestServerTime 會要求報價主機傳送目前時間，時間由 OnNotifyServerTime 事件送回來。在這裡，呼叫本身就是目的，OnNotifyServerTime 送回來的時間可以不用處理。

至於連線就緒、但報價資料不再進來（停格）要怎麼偵測，見〈群益API 報價停止更新怎麼辦〉，本文只講到 keep-alive 為止。

程式怎麼寫？就緒旗標的 6 條做法

1. EnterMonitorLONG 之後，等 OnConnection 的 3003 才訂閱或查商品檔；3001 不算。
2. OnConnection 事件裡只記狀態，訂閱放到事件外面做。
3. 用一個「報價就緒」旗標：只由 3003 翻開，收到斷線類事件時關上，關上之後重新等 3003。
4. 等 3003 要設逾時，時間到就重新連線；等待期間不要重複呼叫 EnterMonitorLONG。
5. 海期報價用 OnConnect 的 3001 判定連線，注意參數順序和國內不同。
6. 連線之後固定每十五秒呼叫一次 RequestServerTime，收盤後也照做。

// 報價就緒旗標：只由 3003 翻開
bool _quoteReady = false;

void OnConnection(int nKind, int nCode)
{
    // 事件裡只記狀態，不在這裡訂閱（官方備註：避免在此事件直接訂閱）
    if (nKind == 3003)                                        // SK_SUBJECT_CONNECTION_STOCKS_READY
        _quoteReady = true;
    else if (nKind == 3002 || nKind == 3021 || nKind == 3033) // 斷線類（這個分類是程式自己決定的）
        _quoteReady = false;
}

// 事件之外（例如計時器）才檢查旗標並訂閱
if (_quoteReady && !_subscribed)
    SubscribeAll();

// keep-alive：官方建議固定每十五秒呼叫一次（EnterMonitorLONG 之後啟動計時器）
keepAliveTimer.Interval = 15000;
keepAliveTimer.Tick += (s, e) => m_pSKQuote.SKQuoteLib_RequestServerTime();

事件簽名對照官方宣告 void OnConnection([in] LONG nKind, [in] LONG nCode)，C# 寫 int。

常見問題

風險揭露

期貨與選擇權屬高槓桿商品，價格波動可能造成超過原始保證金的損失，交易人須自負交易責任。本文為程式開發技術教學，說明報價連線狀態的判讀與就緒判定，不構成投資建議，也不保證任何交易結果。程式化交易並不降低市場風險，反而可能因程式錯誤造成非預期的行為——在報價尚未就緒時就依賴報價做判斷，或連線中斷而程式未察覺，都可能讓程式依據不完整的資料運作。

投資人教育資源

延伸閱讀

• 〈群益API 報價訂閱有哪兩層〉——等到 3003 之後，訂閱的兩條管道。
• 〈群益API 下單初始化有哪 7 步〉——同一個「連上線不等於可以用」的形狀，出現在回報通道。
• 〈群益API 事件回呼跑在哪個執行緒〉——為什麼事件裡只記狀態。
• 〈Python 接群益API 收不到事件〉——海期報價 OnConnect 在 Python 下的實測。

參考資料

• 3001／3003 等代碼的常數與說明，依群益官方元件說明文件錯誤代碼定義表；OnConnection 參數說明與備註、RequestStocks／RequestTicks／RequestStockList 備註、IsConnected 回傳值，依官方「國內報價」章節；OnConnect 宣告與參數說明，依官方「海期報價」章節。
• RequestServerTime 每十五秒呼叫的建議，依官方元件說明文件主手冊（V2.13.57、V2.13.59）的注意事項。
• 斷線類代碼的分類、海期不送出 3003、3003 等待時間、握手期間重複連線的觀察：實作與實測經驗，非官方文件記載。

免責聲明

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