Error envelope
When a request fails, the response shape is:
{
"success": false,
"request_id": "req_abc123",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Daily request quota reached (100 req/day on Free tier)."
}
}
request_id is unique per request — include it when reporting issues.
Status codes
| Code | Meaning | What to do |
|---|
200 | Success | — |
400 | Bad request — invalid params | Check the parameter table in API Reference |
401 | Unauthorized | Verify X-API-Key header is set and the key is valid |
402 | Payment required (Nanopayment) | Sign EIP-3009 authorization and retry |
403 | Forbidden — endpoint not in your plan | Upgrade on Pricing |
404 | Endpoint or symbol not found | Check spelling, symbol format, or try the screener |
429 | Rate limit exceeded | Back off with exponential delay; upgrade plan or use Nanopayment |
500 | Server error | Retry after 1–2s; if persistent, email support |
Retry strategy
For idempotent GET requests:
- First retry: wait 1 second
- Second retry: wait 2 seconds
- Third retry: wait 4 seconds
- Give up and surface the error
Always include the request_id from the failed response when contacting support.
Rate limits per plan
| Plan | Daily requests | Burst |
|---|
| Free | 100 | 10 req/s |
| Pro | 10,000 | 50 req/s |
| Enterprise | Custom | Custom |
| Nanopayment | Unlimited (pay-per-call) | 100 req/s |
The Dashboard shows live usage. Set up a webhook alert at 80% of quota to avoid surprises.
