Error Handling

The SDK uses a hierarchical error system. All error types implement the error interface. Child types unwrap to their parent, so always use errors.As (not a type switch), and test the more specific type first.

Import

The root package is named ssisdk. Use an explicit alias:

import (
    "errors"

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

Error Types

RetryAfterMs, Limit and Remaining are pointers: they are nil when the server did not send the value. Reset is always nil for REST.

Basic Usage

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

Detailed Error Handling

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: do not re-place under a new id before you know whether the first order is live
        log.Printf("Duplicate request id: %v", dup)
    case errors.As(err, &rl):
        if rl.RetryAfterMs != nil {
            log.Printf("Rate limited, retry after %d ms", *rl.RetryAfterMs)
        } else {
            log.Println("Rate limited")
        }
    case errors.As(err, &reauth):
        log.Println("Session expired, a new OTP is needed")
    case errors.As(err, &authErr):
        log.Println("Authentication error")
    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)
    }
}

Because DuplicateRequestError embeds APIError, and ReauthenticationRequiredError, SmartOTPPendingError, SmartOTPRejectedError embed AuthenticationError, the specific case must come before its parent in the switch.

Smart OTP

SmartOTPPendingError is expected while the user has not approved yet. Poll with the same transaction id (EnsureAuthenticated / EnsureAuthenticatedWith poll for you, see Client Classes). SmartOTPRejectedError and ReauthenticationRequiredError are terminal: request a new OTP.

Server Error Codes

ServerErrorCode is a named type for known server codes. The SDK never fails on an unknown code: use ssisdk.LookupServerErrorCode(code) (returns (ServerErrorCode, bool)) or code.IsKnown() to check. Some names alias the same number.

Codes 401101-401104 and 401106-401108 make the SDK stop refreshing and ask for re-authentication (ReauthenticationRequiredError).

Batch Order Errors

Errors of PlaceBatchOrders / CancelBatchOrders (details in Batch Orders):

On a timeout or a dropped connection you cannot know whether the batch reached the system, because write requests are not retried. Reconcile the order status first (for example through order events on streaming). If you must resend, reuse the same ClientRequestID values so the 409 duplicate protection still applies.

A per-order Success == false in BatchOrderResult does not make the call return an error; it is that order's own failure (ErrorCode / ErrorMessage).

Trading WebSocket Errors

See 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):
        // The server refused: 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)
    }
}

(imports context, errors, fmt and the ssisdk alias.)

The WebSocket client does not return *RateLimitError (that type is REST-only); a rate limit appears as TradingWSError with Status 429. TradingWSError never carries signed params. A refused signature (401006, 401008, 401013) in auto mode is re-sent once with the other encoding; if it still fails, check Config.PrivateKey.

Streaming Errors

Errors after the stream connection is up (network drop, token expiry) are not returned by the subscribe methods. Watch them through SetOnConnection (State, Err) and LastError(). When State == "failed", the SDK stops reconnecting and you must authenticate again. See Connection events.

Handling Guidance

• Use errors.As (not a type switch) and test specific types first: DuplicateRequestError before APIError; ReauthenticationRequiredError / SmartOTPPendingError / SmartOTPRejectedError before AuthenticationError; TradingWSError before WebSocketError.
• Catch *ssisdk.AuthenticationError when a token refresh or new OTP is needed.
• Catch *ssisdk.RateLimitError and respect RetryAfterMs (check for nil) for backoff.
• Catch *ssisdk.APIError to handle business errors from the server.
• Catch *ssisdk.WebSocketError when handling streaming connections.
• Catch *ssisdk.ValidationError to validate input before API calls.
• Use *ssisdk.SSIError as a fallback for all SDK errors.
• Do not log tokens, signatures or OTPs yourself. Token and Config print redacted values through String().