Rate Limits

The xQR API enforces two layers of rate limiting to ensure fair usage and platform stability.

Two-Layer System

1. Burst Rate (per API key)

Token-bucket algorithm limiting requests per second. Tokens refill continuously at the plan’s rate.

Plan	Requests/second
Pro	10
Business	50
Enterprise	200

When burst-limited, the API returns 429 Too Many Requests with a Retry-After: 1 header.

2. Monthly Quota (per workspace)

Total API calls allowed per billing cycle, tracked in the database.

Plan	Monthly API Calls
Free	0 (API disabled)
Pro	1,000
Business	25,000
Enterprise	100,000

When the monthly quota is exhausted, all API calls return 429 until the next billing cycle.

Rate Limit Headers

Every v1 response includes these headers:

Header	Description
X-RateLimit-Limit	Monthly quota total
X-RateLimit-Remaining	Monthly calls remaining
X-RateLimit-Burst-Limit	Max requests per second
X-RateLimit-Burst-Remaining	Burst tokens remaining

Handling Rate Limits

const res = await fetch("https://xqr.co/api/v1/links", {
  headers: { Authorization: `Bearer ${apiKey}` },
});

if (res.status === 429) {
  const retryAfter = res.headers.get("Retry-After");
  // Wait and retry
  await new Promise((r) => setTimeout(r, (parseInt(retryAfter || "1")) * 1000));
}

Tip

Check X-RateLimit-Remaining proactively to avoid hitting the limit. Batch operations using the bulk endpoints when possible.

Monitoring Usage

Check your current usage via the API:

curl https://xqr.co/api/v1/workspace/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

Or visit Developers → Usage in your dashboard for a visual breakdown.