Rate Limits

Understand how rate limiting works and how to handle rate limit errors.

Current Limits

Requests per Hour

100

Maximum requests allowed per API key per hour

Requests per Minute

Maximum requests allowed per API key per minute

Rate Limit Headers

Every API response includes headers that tell you about your current rate limit status:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642521600

X-RateLimit-Limit: Maximum requests allowed in the current window

X-RateLimit-Remaining: Number of requests remaining in the current window

X-RateLimit-Reset: Unix timestamp when the rate limit resets

Handling Rate Limit Errors

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "success": false,
  "error": {
    "message": "You have exceeded your rate limit. Please try again in 45 seconds",
    "code": "RATE_LIMIT_EXCEEDED",
    "details": {
      "limit": 100,
      "reset": "2025-01-15T00:45:00.000Z",
      "retryAfter": 45,
      "message": "You have exceeded your rate limit. Please try again in 45 seconds"
    },
    "timestamp": "2025-01-15T00:00:00.000Z"
  }
}

Best Practices

Monitor rate limit headers

Check the X-RateLimit-Remaining header and slow down before hitting the limit.

Implement exponential backoff

If you receive a 429 error, wait before retrying. Use exponential backoff for repeated failures.

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    // Exponential backoff: 1s, 2s, 4s
    const delay = Math.pow(2, i) * 1000;
    await new Promise(resolve => setTimeout(resolve, delay));
  }

  throw new Error('Max retries exceeded');
}

Cache responses

Store frequently accessed data locally to reduce API calls. Player ratings don't change often.

Don't make parallel requests unnecessarily

Making many simultaneous requests will quickly exhaust your rate limit. Batch requests when possible.

Need higher limits?

The current rate limits are designed to be generous for most use cases. If you have a legitimate need for higher limits, please reach out via GitHub Issues with details about your use case.