Error Handling

The API uses standard HTTP status codes and returns all responses in a consistent JSON envelope with success, data, error, and meta fields.

ENVELOPE

Response Format

All API responses — both success and error — follow this standard envelope:

Success Response

{
  "success": true,
  "data": { ... },
  "error": null,
  "meta": {
    "requestId": "req_a1b2c3",
    "timestamp": "2026-03-17T10:30:00Z",
    "version": "v1"
  }
}

Error Response

{
  "success": false,
  "data": null,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The \"code\" parameter is required.",
    "details": "Provide a valid contract code (e.g., AAPL_NASDAQ). Use GET /v1/market/exchanges/{symbol} to find available exchanges."
  },
  "meta": {
    "requestId": "req_x9y8z7w6",
    "timestamp": "2026-03-17T10:30:00Z",
    "version": "v1"
  }
}

SCHEMA

Envelope Fields

Field	Type	Description
`success`	`boolean`	Whether the request was successful
`data`	`object \| array \| null`	The response payload (varies by endpoint)
`error`	`ApiError \| null`	Error details when success is false
`meta`	`ApiMeta`	Request metadata (requestId, timestamp, version)

ApiError Object

Field	Type	Description
`code`	`string`	Machine-readable error code (e.g., "INVALID_PARAMETER")
`message`	`string`	Human-readable error message
`details`	`string \| null`	Additional context about the error

ApiMeta Object

Field	Type	Description
`requestId`	`string`	Unique request identifier for debugging
`timestamp`	`datetime`	Server timestamp of the response
`version`	`string`	API version (e.g., "v1")

STATUS CODES

HTTP Status Codes

Code	Name	Description	How to Fix
`400`	Bad Request	The request body or parameters are invalid.	Check required fields and data types match the schema.
`401`	Unauthorized	Missing or invalid API key / JWT token.	Include a valid X-Api-Key header or JWT Bearer token.
`403`	Forbidden	The API key lacks permission for this action.	Use an active API key with sufficient permissions.
`404`	Not Found	The requested resource does not exist.	Verify the symbol, keyId, or endpoint path.
`429`	Too Many Requests	Rate limit exceeded.	Wait and retry. Check your usage limits via GET /v1/account/usage.
`500`	Internal Server Error	An unexpected error occurred on the server.	Retry the request. Contact support if it persists.

RATE LIMITS

Rate Limiting

The API enforces per-account rate limits to ensure fair usage and platform stability. Rate limit information is included in every response via HTTP headers. Check your limits via GET /v1/account/usage.

Standard Endpoints

120 requests per minute. Applies to most endpoints. Check usage via GET /v1/account/usage.

Market Data Endpoints

300 requests per minute. Applies to market data and options endpoints for higher throughput.

Rate Limit Headers

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Remaining requests in the current window
`X-RateLimit-Reset`	Unix timestamp when the rate limit resets

HANDLING

When Rate Limited

When you exceed the rate limit, the API returns a 429 Too Many Requests response:

{
  "success": false,
  "data": null,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please wait before retrying.",
    "details": "You have exceeded 120 requests per minute."
  },
  "meta": { "requestId": "req_x9y8z7", "version": "v1" }
}

Recommended strategy: Implement exponential backoff with jitter. Read the X-RateLimit-Reset header to know exactly when your limit resets.

TROUBLESHOOTING

Common Issues

401 on Every Request

Ensure you're sending the X-Api-Key header (not Authorization). Check that your key has not been revoked.

CORS Errors

The API supports CORS for authenticated requests. For browser-based calls, ensure your origin is allowed. Server-to-server calls bypass CORS.

Request Timeouts

The API has a 30-second timeout. If you experience timeouts, check your network connection and retry the request.

Error Codes & Rate Limits