Rate Limiting

The Qarion API enforces rate limits to ensure fair usage and platform stability. Every API response includes rate limit headers so you can monitor your consumption.

Default Limits

Limits are applied per API key (or per user/IP for non-key authentication):

Tier	Requests / minute	Requests / hour	Description
standard	60	1,000	Default for all new API keys
premium	300	10,000	For high-throughput integrations
internal	1,000	50,000	Reserved for first-party services

Contact your administrator to upgrade an API key's tier.

Response Headers

Every API response includes the following headers:

Header	Description	Example
X-RateLimit-Limit	Maximum requests allowed in the current window	60
X-RateLimit-Remaining	Requests remaining in the current window	42
X-RateLimit-Reset	Unix timestamp when the window resets	1708200000

Rate Limit Exceeded (429)

When you exceed the limit, the API returns a 429 Too Many Requests response:

{
  "detail": "Rate limit exceeded. Try again in 23 seconds."
}

The response includes a Retry-After header with the number of seconds to wait before retrying.

Best Practices

Implement Exponential Backoff

import time
import httpx

def request_with_backoff(client, method, url, **kwargs):
    max_retries = 3
    for attempt in range(max_retries):
        response = client.request(method, url, **kwargs)
        if response.status_code != 429:
            return response
        
        retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
        time.sleep(retry_after)
    
    return response  # Return last 429 if all retries exhausted

Monitor Your Usage

Check X-RateLimit-Remaining to proactively throttle requests before hitting the limit.

Use the SDK

The Qarion Python SDK includes built-in retry logic with automatic backoff on 429 responses.

Exempt Endpoints

The following endpoints are not rate-limited:

• GET /health — health check
• GET /metrics — Prometheus metrics
• POST /auth/token — authentication
• POST /auth/refresh — token refresh

API Key Tier Configuration

Admins can set a key's rate limit tier at creation time or update it later:

# Create a key with a specific tier
curl -X POST /api-keys/me/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "CI Pipeline", "rate_limit_tier": "premium"}'

# Update an existing key's tier
curl -X PATCH /api-keys/me/api-keys/$KEY_ID \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"rate_limit_tier": "premium"}'