API Reference
Rate Limits and Throttling
Pre-launch
Section
API Reference
Documentation category
Type
Guide
Technical reference
Summary
SwssChain API rate limit tiers, response headers, 429 handling with exponential backoff, and best practices for efficient API usage.
SWSS Foundation Notice

This documentation is restricted to authorised members of the SWSS Developer Community. Access is granted exclusively through SWSS DevHub, after KYB and SWSS Foundation approval.

All SwssChain GitHub repositories are private. Significant updates are currently deploying across the full SWSS Ecosystem. SDK and API specifications are subject to change at any time in accordance with security requirements and SwssChain Foundation governance decisions.

Join SWSS DevHub →Have a question? Use the Need Help? button below.
SDK Update Notice

SWSS SDK v2.1 is deploying across the ecosystem. API signatures may change during this period. Ensure your integration uses the latest schema from SWSS DevHub.

Article Content

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

TierRequests/SecondRequests/DayWebSocket ConnectionsAvailable Via
Free1010,0001DevHub Free registration
Standard100500,0005DevHub Standard plan
Professional1,0005,000,00020DevHub Professional plan
EnterpriseCustomCustomCustomContact SWSS DevHub directly

Rate Limit Response Headers

Every API response includes the following headers so your application can monitor its rate limit consumption in real time:

HeaderDescription
X-RateLimit-LimitYour tier's maximum requests per second
X-RateLimit-RemainingRequests remaining in the current one-second window
X-RateLimit-ResetUnix timestamp when the current window resets
X-RateLimit-TierYour current tier name (e.g. standard)
Retry-AfterPresent 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"

# Example response headers:
# X-RateLimit-Limit: 100
# X-RateLimit-Remaining: 94
# X-RateLimit-Reset: 1747296061
# X-RateLimit-Tier: standard

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