Rate Limits and Throttling
All SwssChain API endpoints are rate limited to protect infrastructure stability and ensure fair access across all registered developers. Rate limits are applied per API key, not per IP address. This means multiple applications using the same API key share a single rate limit allocation: use separate keys for separate projects to maximise available throughput.
Rate Limit Tiers
| Tier | Requests/Second | Requests/Day | WebSocket Connections | Available Via |
| Free | 10 | 10,000 | 1 | DevHub Free registration |
| Standard | 100 | 500,000 | 5 | DevHub Standard plan |
| Professional | 1,000 | 5,000,000 | 20 | DevHub Professional plan |
| Enterprise | Custom | Custom | Custom | Contact SWSS DevHub directly |
Every API response includes the following headers so your application can monitor its rate limit consumption in real time:
| Header | Description |
X-RateLimit-Limit | Your tier's maximum requests per second |
X-RateLimit-Remaining | Requests remaining in the current one-second window |
X-RateLimit-Reset | Unix timestamp when the current window resets |
X-RateLimit-Tier | Your current tier name (e.g. standard) |
Retry-After | Present only on 429 responses: seconds to wait before retrying |
To inspect headers without a response body, use -I (head request):
curl -I https://swssscan.swss.io/api/v1/blocks/latest -H "X-API-Key: your_api_key"
Handling 429 Too Many Requests
When your API key exceeds its rate limit, the API returns HTTP 429 with the error code RATE_LIMIT_EXCEEDED. The response includes a Retry-After header specifying how many seconds to wait before retrying.
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded for tier: standard",
"timestamp": "2026-05-15T10:00:00Z",
"requestId": "req_abc123"
}
}
Implement exponential backoff to handle 429 responses gracefully:
async function fetchWithRetry(url, options, retries = 3) {
for (let i = 0; i < retries; i++) {
const response = await fetch(url, options);
if (response.status !== 429) return response;
const retryAfter = response.headers.get('Retry-After');
const delay = retryAfter
? parseInt(retryAfter) * 1000
: Math.pow(2, i) * 1000;
await new Promise(resolve => setTimeout(resolve, delay));
}
throw new Error('Rate limit exceeded after maximum retries');
}
Best Practices for Staying Within Limits
- Cache responses where data changes infrequently: block data older than a few seconds is stable and safe to cache
- Use WebSocket subscriptions for real-time block and event data instead of polling the REST API at high frequency
- Use the
/blocks/range endpoint for retrieving multiple blocks rather than individual /blocks/{n} requests in a loop
- Use the
/wallet/{address}/portfolio endpoint for dashboard views that need multiple data types: one request instead of four
- Use separate API keys for development and production environments to avoid development traffic consuming production rate limit allocation
- Monitor
X-RateLimit-Remaining in your application logs: implement proactive throttling before hitting 0
Next Steps