Rate Limiting

Google Workspace APIs enforce rate limits to ensure fair usage. Gspace provides utilities to handle rate limiting gracefully.

Understanding Rate Limits

Different APIs have different rate limits:

  • Calendar API: 1,000,000 queries per day
  • Gmail API: 1 billion quota units per day
  • Drive API: 1,000 queries per 100 seconds per user
  • Sheets API: 300 requests per 100 seconds per project

Built-in Rate Limiting

Gspace includes rate limiting utilities:

python
from gspace.utils.rate_limiter import APIRateLimiter, RetryHandler

# Create rate limiter
rate_limiter = APIRateLimiter(
    max_requests_per_minute=60,
    max_requests_per_hour=1000
)

# Use with retry handler
retry_handler = RetryHandler(
    max_retries=3,
    backoff_factor=2
)

Implementing Rate Limiting

Automatic Rate Limiting

python
from gspace.utils.rate_limiter import RateLimiter

limiter = RateLimiter(requests_per_second=10)

@limiter.limit
def make_api_call():
    return calendar.list_events()

# Calls are automatically rate limited
events = make_api_call()

Exponential Backoff

python
from gspace.utils.rate_limiter import RetryHandler

retry_handler = RetryHandler(
    max_retries=5,
    backoff_factor=2,
    max_backoff=60
)

def api_call_with_retry():
    try:
        return calendar.create_event(...)
    except RateLimitError as e:
        if retry_handler.should_retry(e, attempt):
            delay = retry_handler.get_retry_delay(attempt)
            time.sleep(delay)
            return api_call_with_retry()
        raise

Handling Rate Limit Errors

python
from googleapiclient.errors import HttpError

try:
    events = calendar.list_events()
except HttpError as e:
    if e.resp.status == 429:  # Too Many Requests
        # Extract retry-after header
        retry_after = int(e.resp.headers.get('Retry-After', 60))
        time.sleep(retry_after)
        # Retry the request
        events = calendar.list_events()
    else:
        raise

Best Practices

  1. Respect rate limits - Don't exceed API quotas
  2. Implement exponential backoff - Increase delay between retries
  3. Monitor usage - Track API calls and quota consumption
  4. Use batch requests - Reduce number of API calls
  5. Cache responses - Avoid redundant API calls
  6. Distribute requests - Spread requests over time

Monitoring Quota Usage

python
# Check quota usage
quota_info = calendar.get_quota_info()
print(f"Used: {quota_info['used']}")
print(f"Limit: {quota_info['limit']}")
print(f"Remaining: {quota_info['remaining']}")

Quota Management Strategies

Request Distribution

python
import time
from datetime import datetime, timedelta

def distribute_requests(requests, max_per_second=10):
    """Distribute requests evenly over time"""
    interval = 1.0 / max_per_second
    start_time = datetime.now()
    
    for i, request in enumerate(requests):
        if i > 0:
            time.sleep(interval)
        execute_request(request)

Quota Reservation

python
class QuotaManager:
    def __init__(self, daily_limit=1000000):
        self.daily_limit = daily_limit
        self.used = 0
        self.reserved = 0
    
    def reserve(self, amount):
        if self.used + self.reserved + amount > self.daily_limit:
            raise QuotaExceededError()
        self.reserved += amount
    
    def use(self, amount):
        self.used += amount
        self.reserved -= amount