Skip to content
Novrinex Docs

Errors and retries

Every error uses the same JSON envelope:

{
  "error": {
    "code": "INSUFFICIENT_READY_CAPITAL",
    "message": "Available trading balance is too low.",
    "request_id": "req_01J9...",
    "retryable": false,
    "details": {}
  }
}

Log the response request_id. It identifies the failed HTTP request when contacting support.

The SDK raises NovrinexApiError with the HTTP status, code, request ID, retryability, and details.

Common errors

Section titled “Common errors”
HTTP Code Meaning
401 INVALID_SIGNATURE Signature, timestamp, nonce, or key ID is invalid
401 KEY_REVOKED The key or account is inactive
401 KEY_EXPIRED The key has expired
403 SCOPE_REQUIRED The key lacks the required scope
403 IP_NOT_ALLOWED The request source is outside the key allowlist
403 RISK_LIMIT_EXCEEDED The request exceeds an account or key risk limit
404 UNKNOWN_MARKET The market does not exist or is unavailable to the key
404 ORDER_NOT_FOUND The order or recovered request was not found
404 POSITION_NOT_FOUND The position was not found
409 IDEMPOTENCY_CONFLICT The request_id was reused with different content
409 INSUFFICIENT_READY_CAPITAL Available trading capital is too low
409 MARGIN_MODE_IN_USE Use the market and margin settings already active on the account
409 ORDER_CONFIRMATION_PENDING The order is still being confirmed; read it again shortly
409 ROUTE_NOT_READY No eligible execution route is ready
422 INVALID_REQUEST The request does not match the endpoint contract
422 UNSUPPORTED_ORDER The selected market cannot support the requested order behavior
429 RATE_LIMITED The key exceeded its current request quota
503 EXECUTION_UNAVAILABLE A required trading service is temporarily unavailable

Validation example

Section titled “Validation example”
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request did not match the V1 contract.",
    "request_id": "req_01J9...",
    "retryable": false,
    "details": {
      "issues": [
        {
          "type": "missing",
          "loc": ["body", "quantity"],
          "msg": "Field required"
        }
      ]
    }
  }
}

Retry rules

Section titled “Retry rules”
  • Retry GET and HEAD requests only when retryable is true.
  • For HTTP 429, wait for the Retry-After header.
  • Do not blindly retry a timed-out mutation.
  • Recover a timed-out mutation with GET /v1/requests/{request_id}.
  • Reuse the original request_id only with the exact same request body.

Response headers

Section titled “Response headers”
Header Meaning
NVRX-REQUEST-ID Server request identifier
RateLimit-Limit Request quota for the current window
RateLimit-Remaining Requests remaining in the current window
RateLimit-Reset Seconds until the quota window resets
Retry-After Seconds to wait after HTTP 429