Rate Limits & Errors
Rate Limits & Error Codes
Understanding request quotas, rate limiting behavior, and error response handling.
Rate Limits by Tier
| Tier | REST Limit | Burst | WebSocket |
|---|---|---|---|
| STREAML1 | 120 req/min | 20 | N/A |
| QUANTL2 | 3,000 req/min | 50 | N/A |
| PULSEL3 | 600,000 req/min | 1,000 | 5 connections |
| ORACLEL4 | Custom | Custom | 10 connections |
Rate Limit Headers
Every response includes rate limit information in headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests per window |
X-RateLimit-Remaining | Requests remaining in current window |
X-RateLimit-Reset | Unix timestamp when the window resets |
Retry-After | Seconds to wait (only on 429 responses) |
HTTP Status Codes
| Code | Status | Description |
|---|---|---|
200 | Success | Request processed successfully |
400 | Bad Request | Invalid parameters or missing required fields |
401 | Unauthorized | Missing or invalid API key |
403 | Forbidden | API key lacks permission for this tier/endpoint |
404 | Not Found | Endpoint or resource does not exist |
429 | Rate Limited | Too many requests. Check Retry-After header. |
500 | Server Error | Internal error. Contact support if persistent. |
Error Response Format
All error responses follow a consistent JSON structure:
Error Response
{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Retry after 30 seconds.",
"retry_after": 30
}
}Best Practices
Respect rate limits
Check X-RateLimit-Remaining before making requests. Implement exponential backoff on 429 responses.
Cache responses
Most endpoints have 30s Redis cache. Polling faster than 30s returns the same data and wastes quota.
Use WebSocket for real-time
For real-time event monitoring, WebSocket is more efficient than polling the REST API.
Handle errors gracefully
Always check the HTTP status code and parse error responses. Log errors for debugging.