Skip to content

Error Handling Overview

Use this section to understand why a Nubra API or SDK request failed and what your application should do next. It covers authentication issues, invalid request payloads, stale instruments, order rejections, timeouts, WebSocket disconnects, and support-ready debugging details.

First Response Flow

Failure observed
      |
      v
Identify where it failed: request / auth / instrument / order / WebSocket / network
      |
      v
Does this affect order state?
      |                         |
     Yes                        No
      |                         |
      v                         v
Reconcile orderbook       Classify by status/code
      |                         |
      v                         v
State known?              Retryable?
 |       |                  |       |
Yes      No                Yes      No
 |       |                  |       |
 v       v                  v       v
Update   Escalate       Retry cap   Fail gracefully

How to Use This Section

Page Use it for
Auth & Session Login, token, MPIN, TOTP, device ID, and IP whitelist issues.
Instruments & Ref Data Stale ref_id, exchange mismatch, expired contracts, instrument lookup.
Market Data Historical data, option chain, current price, and market quote errors.
WebSocket / Realtime Reconnect, re-subscribe, heartbeat, stream weight, order update gaps.
Orders, RMS & Exchange Placement, modify/cancel, margin, risk, and exchange rejection handling.
Portfolio Holdings, positions, funds, stale portfolio snapshots, environment mismatch.
Rate Limits & Quotas Trading OPS caps, historical data limits, WebSocket weight limits.
Retry & Reconciliation Safe retries, idempotency, unknown order state, timeout recovery.
Logging & Monitoring Trace IDs, audit fields, metrics, alerts, support bundle.

Use one consistent shape in your application, even when raw responses vary by endpoint or SDK method:

{
  "success": false,
  "error": {
    "code": "ORDER_TIMEOUT",
    "source": "OMS",
    "category": "ORDER_STATE_UNKNOWN",
    "message": "Order status could not be confirmed",
    "user_message": "Order confirmation is delayed. We are checking the latest status.",
    "retryable": false,
    "requires_reconciliation": true,
    "severity": "high",
    "trace_id": "abc123",
    "timestamp": "2026-05-05T10:20:00Z"
  }
}

Practical Rules

  • Classify before retrying.
  • Check order status before repeating an order placement, modify, or cancel request.
  • Do not retry validation, RMS, margin, holdings, lot-size, or price-band failures.
  • Most documented SDK/API errors should not be retried with the same payload.
  • Show users a clear message, and keep the full technical response in your logs.
  • Attach trace IDs, order IDs, basket IDs, strategy tags, and retry counts to every failure.
NEO Assistant