Rate Limits

Understanding Rate Limits

FalconQ enforces limits at two layers: a per-second request rate (enforced as a rolling 60-second window) and a monthly quota per billing cycle. Streaming products (WebSocket and gRPC) are limited by concurrent connections rather than per-message counts.

Plan Limits

FalconQ has two plans: Free and All Access ($100/month). Check your current plan in the dashboard.

Limits apply per account, not per key — all of your keys share the same rate window and monthly quota. WebSocket, gRPC, and FalconStream streaming require an All Access subscription.

How the Rate Window Works

The per-second rate is enforced over a rolling 60-second window: 10 req/s means up to 600 requests in any 60-second span (3,000 for All Access at 50 req/s). Short bursts above your per-second rate are fine as long as the window total stays under the limit. All JSON-RPC methods count equally — resource-intensive calls like getProgramAccounts cost one request like any other, but respond faster when you narrow them with filters and dataSlice.

Rate Limit Headers

Successful RPC responses include headers to help you track usage and latency:

HTTP/2 200 OK
x-rate-limit-remaining: 547
x-proxy-region: fra
x-proxy-latency: 2
x-upstream-latency: 38

• x-rate-limit-remaining — Requests remaining in the current 60-second window
• x-proxy-region — Region that served the request
• x-proxy-latency — Milliseconds spent inside the FalconQ proxy
• x-upstream-latency — Milliseconds spent waiting on the Solana upstream

When rate limited, the response includes a Retry-After header with the seconds until the window frees up.

Handling 429 Rate Limit Errors

When you exceed your rate limit, the API returns a 429 status code with a Retry-After header:

HTTP/2 429 Too Many Requests
Retry-After: 15

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32004,
    "message": "Rate limit exceeded"
  },
  "id": null
}

// JavaScript — implementing rate limit backoff
async function fetchWithBackoff(url, options, maxRetries = 5) {
  for (let i = 0; i <= maxRetries; i++) {
    const response = await fetch(url, options)

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '1')
      const delay = retryAfter * 1000 * Math.pow(2, i) // Exponential backoff
      console.warn(`Rate limited. Retrying in ${delay}ms...`)
      await new Promise(r => setTimeout(r, delay))
      continue
    }

    return response
  }

  throw new Error('Max retries exceeded')
}

Troubleshooting Common Issues

WebSocket & gRPC Streaming Limits

The request-rate window is checked once when a WebSocket connection or gRPC stream is opened — individual subscription updates do not count against your request rate.