Rate Limiting & Usage Guidelines

Understand API rate limits, usage tracking, and best practices for efficient API consumption.

Rate Limiting Overview

All API requests are subject to rate limiting to ensure fair usage and system stability. Rate limits are enforced per API key and are configurable when creating API keys.

Default Rate Limits

100 requests per 15-minute window
Sliding window implementation
Resets automatically as time progresses

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1640995200

X-RateLimit-Limit

Maximum requests allowed in the time window

X-RateLimit-Remaining

Number of requests remaining in current window

X-RateLimit-Reset

Unix timestamp when the window resets

Rate Limit Exceeded (429)

When rate limits are exceeded, the API returns a 429 Too Many Requests status:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Try again later."
}

Best Practice

Always check rate limit headers and implement exponential backoff when approaching limits.

Custom Rate Limits

You can configure custom rate limits when creating API keys:

POST /api/v1/api-keys
{
  "name": "High Volume Key",
  "permissions": ["qrcode:create", "qrcode:read"],
  "rateLimit": {
    "maxRequests": 500,
    "windowMs": 900000
  }
}

Parameter	Description	Default
maxRequests	Maximum requests allowed in window	100
windowMs	Time window in milliseconds	900000 (15 min)

Usage Tracking

All API requests are logged for usage analysis and billing purposes:

Endpoint accessed and HTTP method
Response status code and time
Request body size and response time
IP address and user agent
Timestamp of request

Usage data is retained for 90 days and can be accessed via the usage tracking endpoints.

Best Practices

✓ Do

Monitor rate limit headers
Implement exponential backoff
Cache responses when possible
Use appropriate request intervals
Request higher limits if needed

✗ Don't

Ignore rate limit headers
Make unnecessary duplicate requests
Use aggressive polling intervals
Share API keys between applications
Retry immediately after 429 errors

Monitoring Usage

Track your API usage with the usage endpoints:

Get Usage Statistics

GET /api/v1/api-usage?period=day

Returns aggregated usage statistics for the specified period.

Get Detailed Logs

GET /api/v1/api-usage/details?limit=100

Returns detailed request logs with pagination.

Upgrading Limits

Need higher rate limits? Contact support or upgrade your plan:

For enterprise usage requiring higher limits, please contact our support team. We can configure custom rate limits based on your specific needs.