Rate Limits

API rate limiting and throttling policies for Lager Guru.

Overview

Lager Guru implements rate limiting to ensure fair usage and system stability. This document outlines rate limit policies and best practices.

Rate Limit Policies

API Endpoints

Standard Endpoints

• Limit: 1000 requests per minute
• Burst: 200 requests per 10 seconds
• Window: 1 minute rolling window

Authentication Endpoints

• Limit: 60 requests per minute
• Burst: 10 requests per 10 seconds
• Window: 1 minute rolling window

Webhook Endpoints

• Limit: 500 requests per minute
• Burst: 100 requests per 10 seconds
• Window: 1 minute rolling window

Database Queries

Read Queries

• Limit: 5000 queries per minute
• Burst: 1000 queries per 10 seconds
• Window: 1 minute rolling window

Write Queries

• Limit: 1000 queries per minute
• Burst: 200 queries per 10 seconds
• Window: 1 minute rolling window

Rate Limit Headers

All API responses include rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 850
X-RateLimit-Reset: 1640995200
X-RateLimit-Used: 150

Header Descriptions

• X-RateLimit-Limit: Maximum requests allowed in the window
• X-RateLimit-Remaining: Remaining requests in current window
• X-RateLimit-Reset: Unix timestamp when the limit resets
• X-RateLimit-Used: Number of requests used in current window

Rate Limit Responses

429 Too Many Requests

When rate limit is exceeded:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please retry after 60 seconds.",
  "retry_after": 60,
  "limit": 1000,
  "remaining": 0,
  "reset_at": "2025-01-15T10:30:00Z"
}

Best Practices

Handling Rate Limits

1. Monitor Headers: Always check rate limit headers in responses
2. Implement Backoff: Use exponential backoff when rate limited
3. Cache Responses: Cache frequently accessed data
4. Batch Requests: Combine multiple operations when possible
5. Use Webhooks: Prefer webhooks over polling

Example: Exponential Backoff

async function requestWithRetry(url: string, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const response = await fetch(url);
      
      if (response.status === 429) {
        const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
      
      return response;
    } catch (error) {
      if (i === retries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
    }
  }
}

Example: Rate Limit Monitoring

function checkRateLimit(headers: Headers) {
  const remaining = parseInt(headers.get('X-RateLimit-Remaining') || '0');
  const limit = parseInt(headers.get('X-RateLimit-Limit') || '1000');
  
  if (remaining < limit * 0.1) {
    console.warn('Rate limit approaching. Remaining:', remaining);
  }
  
  return {
    remaining,
    limit,
    resetAt: new Date(parseInt(headers.get('X-RateLimit-Reset') || '0') * 1000)
  };
}

Enterprise Limits

Enterprise plans include higher rate limits:

• API Endpoints: 10,000 requests per minute
• Database Queries: 50,000 queries per minute
• Webhooks: 5,000 requests per minute
• Custom Limits: Available upon request

Monitoring

Rate Limit Metrics

Monitor rate limit usage via:

• Dashboard: Real-time rate limit metrics
• API: Rate limit status endpoint
• Webhooks: Rate limit notifications

Example: Rate Limit Status

curl -X GET https://api.lager-guru.hashmatrix.de/v1/rate-limit/status \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "api": {
    "limit": 1000,
    "remaining": 750,
    "reset_at": "2025-01-15T10:30:00Z"
  },
  "database": {
    "limit": 5000,
    "remaining": 4200,
    "reset_at": "2025-01-15T10:30:00Z"
  }
}

Troubleshooting

Common Issues

Frequent 429 errors

• Review request patterns
• Implement caching
• Use batch operations
• Consider upgrading plan

Rate limit headers missing

• Ensure using latest API version
• Check authentication headers
• Verify endpoint compatibility

Related Documentation

• API Reference - Complete API documentation
• Authentication - Authentication guide
• Developer Onboarding - Getting started guide

Next Steps

• API Reference - Explore API endpoints
• Developer Onboarding - Start development