Xử lý lỗi

SDK sử dụng hệ thống error phân cấp. Tất cả error type đều implement interface error. Error con unwrap về error cha, nên hãy luôn dùng errors.As (không dùng type switch) và kiểm tra type cụ thể hơn trước.

Import

Package gốc có tên ssisdk. Dùng alias tường minh:

import (
    "errors"

    ssisdk "github.com/SSI-Securities-Inc/ssi-sdk-go/v3"
)

Danh sách Error

RetryAfterMs, Limit và Remaining là pointer: bằng nil khi server không gửi giá trị. Reset luôn là nil với REST.

Sử dụng cơ bản

token, err := auth.Authenticate(os.Getenv("SSI_OTP"))
if err != nil {
    log.Printf("Error: %v", err)
}

Xử lý lỗi chi tiết

result, err := t.Trading.PlaceLimitOrder("YOUR_ACCOUNT_NO", "SSI", trading.OrderSideBuy, 100, 68000)
if err != nil {
    var dup *ssisdk.DuplicateRequestError
    var rl *ssisdk.RateLimitError
    var reauth *ssisdk.ReauthenticationRequiredError
    var authErr *ssisdk.AuthenticationError
    var apiErr *ssisdk.APIError
    var vErr *ssisdk.ValidationError
    var wsErr *ssisdk.WebSocketError

    switch {
    case errors.As(err, &dup):
        // 409: đừng đặt lại với id mới trước khi biết lệnh đầu có còn hiệu lực không
        log.Printf("Trùng request id: %v", dup)
    case errors.As(err, &rl):
        if rl.RetryAfterMs != nil {
            log.Printf("Rate limited, retry sau %d ms", *rl.RetryAfterMs)
        } else {
            log.Println("Rate limited")
        }
    case errors.As(err, &reauth):
        log.Println("Phiên hết hạn, cần OTP mới")
    case errors.As(err, &authErr):
        log.Println("Lỗi xác thực")
    case errors.As(err, &apiErr):
        log.Printf("API error %d (%s): %s", apiErr.StatusCode, apiErr.Code, apiErr.Message)
    case errors.As(err, &vErr):
        log.Printf("Validation: %s", vErr.Message)
    case errors.As(err, &wsErr):
        log.Printf("WebSocket: %s", wsErr.Message)
    default:
        log.Printf("Unknown error: %v", err)
    }
}

Vì DuplicateRequestError embed APIError, còn ReauthenticationRequiredError, SmartOTPPendingError, SmartOTPRejectedError embed AuthenticationError, nên case cụ thể phải đặt trước case cha trong switch.

Smart OTP

SmartOTPPendingError là trạng thái bình thường khi người dùng chưa duyệt. Poll với cùng transaction id (EnsureAuthenticated / EnsureAuthenticatedWith tự poll giúp bạn, xem Client Classes). SmartOTPRejectedError và ReauthenticationRequiredError là lỗi kết thúc: hãy yêu cầu OTP mới.

Server Error Codes

ServerErrorCode là named type cho các mã lỗi server đã biết. SDK không bao giờ lỗi vì mã chưa biết: dùng ssisdk.LookupServerErrorCode(code) (trả (ServerErrorCode, bool)) hoặc code.IsKnown() để kiểm tra. Một số tên là alias của cùng một số.

Các mã 401101-401104 và 401106-401108 khiến SDK ngừng refresh và yêu cầu xác thực lại (ReauthenticationRequiredError).

Batch Order Errors

Lỗi của PlaceBatchOrders / CancelBatchOrders (chi tiết trong Batch Orders):

Khi timeout hoặc mất kết nối, bạn không thể biết batch đã tới hệ thống hay chưa vì request ghi không được retry. Hãy đối soát trạng thái lệnh trước (ví dụ qua order event của streaming). Nếu buộc phải gửi lại, dùng lại đúng các ClientRequestID cũ để cơ chế chống trùng 409 vẫn có tác dụng.

Success == false ở từng BatchOrderResult không làm lời gọi trả error; đó là lỗi riêng của lệnh đó (ErrorCode / ErrorMessage).

Trading WebSocket Errors

Xem Trading WebSocket.

func reportWSError(op string, err error) {
    var wsErr *ssisdk.TradingWSError
    var vErr *ssisdk.ValidationError
    var connErr *ssisdk.WebSocketError

    switch {
    case errors.As(err, &wsErr):
        // Server từ chối: Status, ErrorCode, ServerMessage.
        fmt.Printf("%s: server refused status=%d code=%s: %s\n",
            op, wsErr.Status, wsErr.ErrorCode, wsErr.ServerMessage)
    case errors.As(err, &vErr):
        fmt.Printf("%s: invalid input (nothing was sent): %v\n", op, vErr)
    case errors.Is(err, context.DeadlineExceeded), errors.Is(err, context.Canceled):
        fmt.Printf("%s: context ended: %v\n", op, err)
    case errors.As(err, &connErr):
        fmt.Printf("%s: websocket error: %v\n", op, connErr)
    default:
        fmt.Printf("%s: error: %v\n", op, err)
    }
}

(cần import context, errors, fmt và alias ssisdk.)

WebSocket client không trả *RateLimitError (type này chỉ dành cho REST); rate limit xuất hiện dưới dạng TradingWSError với Status 429. TradingWSError không bao giờ mang params đã ký. Khi chữ ký bị từ chối (401006, 401008, 401013) ở chế độ auto, SDK gửi lại một lần với encoding còn lại; nếu vẫn lỗi, hãy kiểm tra Config.PrivateKey.

Streaming Errors

Lỗi sau khi stream đã kết nối (rớt mạng, token hết hạn) không được trả về từ các hàm subscribe. Hãy theo dõi qua SetOnConnection (State, Err) và LastError(). Khi State == "failed", SDK ngừng reconnect và bạn phải xác thực lại. Xem Connection events.

Hướng dẫn xử lý

• Dùng errors.As (không dùng type switch) và kiểm tra type cụ thể trước: DuplicateRequestError trước APIError; ReauthenticationRequiredError / SmartOTPPendingError / SmartOTPRejectedError trước AuthenticationError; TradingWSError trước WebSocketError.
• Bắt *ssisdk.AuthenticationError khi cần làm mới token hoặc lấy OTP mới.
• Bắt *ssisdk.RateLimitError và tuân thủ RetryAfterMs (kiểm tra nil) để backoff.
• Bắt *ssisdk.APIError để xử lý lỗi nghiệp vụ từ server.
• Bắt *ssisdk.WebSocketError khi xử lý kết nối streaming.
• Bắt *ssisdk.ValidationError để kiểm tra input trước khi gọi API.
• Dùng *ssisdk.SSIError làm fallback cho tất cả lỗi SDK.
• Đừng tự log token, chữ ký hay OTP. Token và Config in giá trị đã che qua String().