Reference

Error Codes

Complete reference for HTTP status codes, error response format, and common troubleshooting scenarios.

Error Response Format

All error responses follow this JSON structure. The request_id field appears on 500 errors for support escalation.

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "request_id": "req_7f3a2b1c-...",
  "retry_after": 12
}

Stack traces are never exposed. Only the opaque request_id is returned for 500 errors.

HTTP Status Codes

Code	Status	Description	Action
200	OK	Request completed successfully.	None required.
400	Bad Request	Missing or invalid parameter.	Check the "field" value in the error response.
401	Unauthorized	API key missing or invalid.	Verify the X-API-Key header is present and correct.
403	Forbidden	API key valid but tier insufficient.	Upgrade to the required tier for this endpoint.
404	Not Found	Endpoint or resource does not exist.	Verify the path and parameter values.
429	Too Many Requests	Rate limit exceeded.	Wait for the number of seconds in the Retry-After header.
500	Internal Error	Server-side error.	Retry after 30 seconds. If persistent, contact support with the request_id.
503	Service Unavailable	Temporary maintenance or overload.	Retry after 30 seconds.

Rate Limits

For detailed rate limit tiers, burst allowances, and WebSocket connection limits, see the Rate Limits page.

Handling 429 (Rate Limited)

Python

import time, requests

def safe_request(url, headers):
    resp = requests.get(url, headers=headers)
    if resp.status_code == 429:
        wait = int(resp.headers.get("Retry-After", 60))
        time.sleep(wait)
        resp = requests.get(url, headers=headers)
    return resp.json()

Common Error Scenarios

Missing API KeyGET /api/v1/heatmap?symbol=BTCUSDT

{
  "error": "Unauthorized",
  "code": "MISSING_API_KEY",
  "message": "X-API-Key header is required."
}

Fix: Add the X-API-Key header to every request.

Invalid API KeyGET /api/v1/heatmap?symbol=BTCUSDT -H "X-API-Key: invalid"

{
  "error": "Unauthorized",
  "code": "INVALID_API_KEY",
  "message": "The provided API key is not recognized."
}

Fix: Verify the key starts with nxg_ and matches your Developer Portal key.

Tier InsufficientGET /api/v1/signals/BTCUSDT (with STREAM key)

{
  "error": "Forbidden",
  "code": "TIER_INSUFFICIENT",
  "message": "This endpoint requires PULSE tier.",
  "required_tier": "PULSE",
  "current_tier": "STREAM"
}

Fix: Upgrade your subscription to PULSE or higher.

Rate Limit ExceededRapid sequential requests

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 12,
  "request_id": "req_7f3a2b1c-4e5d-6a7b-8c9d-0e1f2a3b4c5d"
}

Fix: Implement exponential backoff. Read the Retry-After header value.

Invalid SymbolGET /api/v1/oi/INVALIDUSDT

{
  "error": "Bad Request",
  "code": "INVALID_SYMBOL",
  "message": "Symbol INVALIDUSDT is not supported.",
  "supported": ["BTCUSDT", "ETHUSDT", "..."]
}

Fix: Use one of the 10 supported symbols. See /docs/data-model for the full list.

Missing Required ParameterGET /api/v1/market/funding (missing :symbol)

{
  "error": "Bad Request",
  "code": "MISSING_PARAMETER",
  "field": "symbol",
  "message": "The symbol parameter is required."
}

Fix: Check the endpoint documentation for required parameters.

WebSocket Auth Failedwss://nexusglass.live/ws/fastfeed (no token)

{
  "type": "ERROR",
  "payload": {
    "code": "AUTH_FAILED",
    "message": "Invalid or expired API key"
  }
}

Fix: Pass your API key via the ?token= query parameter.

Server ErrorAny endpoint during transient failure

{
  "error": "Internal Server Error",
  "code": "INTERNAL_ERROR",
  "request_id": "req_7f3a2b1c-4e5d-6a7b-8c9d-0e1f2a3b4c5d"
}

Fix: Retry after 30 seconds. If the error persists, contact support with the request_id.

Authentication Rate Limits API Reference

Error Response Format

All error responses follow this JSON structure. The request_id field appears on 500 errors for support escalation.

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "request_id": "req_7f3a2b1c-...",
  "retry_after": 12
}

Stack traces are never exposed. Only the opaque request_id is returned for 500 errors.

HTTP Status Codes

Code	Status	Description	Action
200	OK	Request completed successfully.	None required.
400	Bad Request	Missing or invalid parameter.	Check the "field" value in the error response.
401	Unauthorized	API key missing or invalid.	Verify the X-API-Key header is present and correct.
403	Forbidden	API key valid but tier insufficient.	Upgrade to the required tier for this endpoint.
404	Not Found	Endpoint or resource does not exist.	Verify the path and parameter values.
429	Too Many Requests	Rate limit exceeded.	Wait for the number of seconds in the Retry-After header.
500	Internal Error	Server-side error.	Retry after 30 seconds. If persistent, contact support with the request_id.
503	Service Unavailable	Temporary maintenance or overload.	Retry after 30 seconds.

import time, requests def safe_request(url, headers): resp = requests.get(url, headers=headers) if resp.status_code == 429: wait = int(resp.headers.get("Retry-After", 60)) time.sleep(wait) resp = requests.get(url, headers=headers) return resp.json()

Common Error Scenarios

Missing API KeyGET /api/v1/heatmap?symbol=BTCUSDT

{
  "error": "Unauthorized",
  "code": "MISSING_API_KEY",
  "message": "X-API-Key header is required."
}

Fix: Add the X-API-Key header to every request.

Invalid API KeyGET /api/v1/heatmap?symbol=BTCUSDT -H "X-API-Key: invalid"

{
  "error": "Unauthorized",
  "code": "INVALID_API_KEY",
  "message": "The provided API key is not recognized."
}

Fix: Verify the key starts with nxg_ and matches your Developer Portal key.

Tier InsufficientGET /api/v1/signals/BTCUSDT (with STREAM key)

{
  "error": "Forbidden",
  "code": "TIER_INSUFFICIENT",
  "message": "This endpoint requires PULSE tier.",
  "required_tier": "PULSE",
  "current_tier": "STREAM"
}

Fix: Upgrade your subscription to PULSE or higher.

Rate Limit ExceededRapid sequential requests

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 12,
  "request_id": "req_7f3a2b1c-4e5d-6a7b-8c9d-0e1f2a3b4c5d"
}

Fix: Implement exponential backoff. Read the Retry-After header value.

Invalid SymbolGET /api/v1/oi/INVALIDUSDT

{
  "error": "Bad Request",
  "code": "INVALID_SYMBOL",
  "message": "Symbol INVALIDUSDT is not supported.",
  "supported": ["BTCUSDT", "ETHUSDT", "..."]
}

Fix: Use one of the 10 supported symbols. See /docs/data-model for the full list.

Missing Required ParameterGET /api/v1/market/funding (missing :symbol)

{
  "error": "Bad Request",
  "code": "MISSING_PARAMETER",
  "field": "symbol",
  "message": "The symbol parameter is required."
}

Fix: Check the endpoint documentation for required parameters.

WebSocket Auth Failedwss://nexusglass.live/ws/fastfeed (no token)

{
  "type": "ERROR",
  "payload": {
    "code": "AUTH_FAILED",
    "message": "Invalid or expired API key"
  }
}

Fix: Pass your API key via the ?token= query parameter.

Server ErrorAny endpoint during transient failure

{
  "error": "Internal Server Error",
  "code": "INTERNAL_ERROR",
  "request_id": "req_7f3a2b1c-4e5d-6a7b-8c9d-0e1f2a3b4c5d"
}

Fix: Retry after 30 seconds. If the error persists, contact support with the request_id.

Error Codes

Error Response Format

HTTP Status Codes

Rate Limits

Handling 429 (Rate Limited)

Common Error Scenarios

NEXUS GLASS

Error Codes

Error Response Format

HTTP Status Codes

Rate Limits

Handling 429 (Rate Limited)

Common Error Scenarios