群益API 登入錯誤怎麼判讀？這 2 類錯誤碼決定你該不該繼續查程式

先確認你在哪一關：如果連元件都載入不起來、登入視窗根本開不了，那是更前面的問題（見文末延伸閱讀）。本篇處理的是元件正常、程式跑得動，但 SKCenterLib_Login 回了一個數字的情況——也就是最典型的群益API 登入錯誤。

拿到那個數字之後，多數人的下一步是打開程式碼開始翻。但有相當一部分的碼，無論你把程式讀幾遍都不會有答案——因為問題根本不在程式裡。這篇要給你的不是「每個碼怎麼解」，而是先判斷這個碼該不該讓你繼續查程式。

群益API 登入錯誤代碼怎麼判讀？先問「這是程式的問題嗎」

把群益API 登入錯誤碼分成兩類，判讀就有了方向：

認出一個碼屬於 B 類，本身就是有用的資訊——它讓你停止在正確的程式碼裡找錯。

這篇只分這兩類，不再細分。分得越細，B 類看起來越像一份可以照著做的清單，但那正好是它不是的東西。

判讀的第一步：讓 API 自己把碼翻成文字

判讀群益API 登入錯誤的第一個動作不是翻程式碼，是把數字換成文字。SKCenterLib_GetReturnCodeMessage 可以直接把回傳碼換成官方訊息：

int nCode = m_pSKCenter.SKCenterLib_Login(userId, password);
string message = m_pSKCenter.SKCenterLib_GetReturnCodeMessage(nCode);

不要自己維護一份錯誤碼中文對照表。 錯誤碼會隨版本增加——9996 就是較新版本才出現的碼，自建的表不會自己長出它，於是你會拿到一個查不到的數字，然後開始懷疑是自己漏了什麼文件。

把官方訊息一併記進日誌，之後排查省下來的時間會遠超過這兩行的成本。

A 類：程式端可解的群益API 登入錯誤代碼

這一類群益API 登入錯誤的共同點是動作都發生在你的程式或你的機器上，所以官方說明可以直接照著做。

有幾個碼沒有正式常數名，只有說明文字，表格裡以 — 表示——不要自己替它們發明常數名，那會在協作時造成混淆。

B 類：不是程式能解決的群益API 登入錯誤代碼

這一類群益API 登入錯誤指向的是帳戶側的狀態。列出來的目的只有一個：讓你認出它、然後停止在程式裡找原因。

這一類的碼，程式端做不了什麼。 改程式、換寫法、重裝元件都不會讓它們消失，因為要改變的狀態不在你的機器上。認出這件事，比繼續除錯有價值。

這篇不會告訴你這些狀態各自該怎麼處理——那超出「寫程式」這個主題的範圍。本篇能給的是判別：你卡在哪一類。

如果有遇到這類的問題可以先跟您的營業員反應。

登入看起來成功了，功能卻全部回 1000？

這是整篇最值得記住的一種群益API 登入錯誤，因為它的錯誤訊息會主動把你導向錯誤的方向。

症狀：主畫面開得起來、看起來登入成功了，但行情、回報、下單全部回 1000。而 1000 的官方說明是「請先由 Center 進行登入動作」——於是你回頭去檢查登入流程，在一段完全正確的程式碼裡繞圈子。

機制：登入回傳 600～699 並不是失敗，而是未使用雙因子的登入成功。如果程式只判斷「回傳值是不是 0」，就會把這個狀態當成失敗；或者更麻煩——當成完全正常，直接放行進主畫面。而在這個狀態下，後端可能把後續功能全部擋掉，使用者看到的就是一片 1000。

關鍵在於：登入回傳值有三種狀態，不是兩種。

// 登入回傳值有三種狀態，不能只判斷 == 0
int nCode = m_pSKCenter.SKCenterLib_Login(userId, password);
string message = m_pSKCenter.SKCenterLib_GetReturnCodeMessage(nCode);

if (nCode == 0)
{
    // 雙因子登入成功
    OnLoginSucceeded();
}
else if (nCode >= 600 && nCode <= 699)
{
    // 登入成功，但未使用雙因子：可以繼續，但後續功能可能全部被擋
    // 這裡一定要明確提示，否則使用者只會看到一片 1000
    OnLoginSucceededWithWarning(nCode, message);
}
else
{
    OnLoginFailed(nCode, message);
}

程式端該做的有三件：把 600–699 當成獨立的第三種狀態、在這個狀態下明確提示使用者、並把 SKCenterLib_GetReturnCodeMessage 取到的官方訊息一併顯示出來。這個狀態與憑證有關，屬於帳戶側的範疇；程式這一端能做也該做的，是讓使用者知道自己現在在哪個狀態，而不是讓他對著一片 1000 猜。

1097 遇到了，要馬上去改防火牆嗎？

先不要。

1097 的官方說明是「Telnet 登入主機失敗，請確認您的環境（Firewall 及 hosts 等）」，指向的是環境設定。但它也可能只是暫時性的連線卡住，重連就通。

建議的順序是先重試幾次，數次仍失敗才往環境設定的方向查。理由不是機率，是成本不對稱——重試花你幾秒鐘，調防火牆規則與 hosts 檔可能花掉半天，而問題說不定在你動手之前就已經自己好了。就算暫時性只佔一小部分，先重試仍然划算。

1098 屬於同一層（同意書查詢主機連線失敗），成本結構一樣，套用同樣的處理順序即可。這類連線層的群益API 登入錯誤，先給它一點時間再動手改設定。

常見問題

風險揭露

期貨與選擇權屬高槓桿商品，價格波動可能造成超過原始保證金的損失，交易人須自負交易責任。本文為程式開發技術教學，說明登入回傳碼的判讀方式，不構成投資建議，也不保證任何交易結果。程式化交易並不降低市場風險，反而可能因程式錯誤造成非預期的委託行為。

投資人教育資源

延伸閱讀

• 〈群益API 是什麼〉——讀懂群益API 登入錯誤之前，SKCenterLib_Login 與 OnReplyMessage 的定位在那篇講過。
• 〈群益API 註冊失敗怎麼處理〉——訊息是「擷取元件 CLSID 失敗」時，問題在更前面的階段。
• 〈群益API 元件無法載入〉——元件被作業系統擋下的情況，同樣在登入之前。
• 〈群益API 下單初始化有哪 7 步〉——1038（憑證尚未驗章）屬於初始化鏈的一環，那篇有完整順序。

參考資料

• 錯誤碼代號、常數名與官方說明文字，出自群益官方元件使用說明的錯誤碼表；9996 為較新版本新增。
• 600 系列的語意與後續呼叫的連鎖現象，為應用端實測紀錄，非官方文件記載。
• 1097 先重試再查環境設定的處理順序，為實務歸納，非官方說法；官方說明指向環境設定。

免責聲明

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