Limits & Quotas

1. Rate limits — requests per minute, per endpoint
2. Request quotas — total requests per billing period

​

Rate limits

​

Per-endpoint limits

​

How rate limits work

• Limits are tracked per API key, per endpoint
• Each endpoint has its own independent counter
• The window is rolling (not aligned to the clock minute)

​

When you hit a rate limit

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded for /generate: 500 requests per 1 minute(s)",
  "limit": 500,
  "endpoint": "/generate",
  "retry_after": 45
}

• Retry-After header with seconds to wait
• X-RateLimit-Reset header with reset timestamp

​

Request quotas

​

What counts toward quota

​

When you hit quota

{
  "error": "REQUEST_LIMIT_EXCEEDED",
  "message": "Request limit exceeded: 10000/10000 monthly requests used",
  "limit": 10000,
  "used": 10000,
  "period": "monthly",
  "reset_at": "2024-02-01T00:00:00Z"
}

​

Checking your quota

​

Order of checks

​

For POST /api/v1/generate

1. Authentication — Is the API key valid?
2. Request quota — Are you within monthly quota?
3. Rate limit — Are you within per-minute limits?
4. Request processing — Generate the output

​

For other authenticated endpoints

1. Authentication
2. Rate limit
3. Request processing

​

Best practices

​

Avoid rate limits

• Use /preview for testing (free, watermarked)
• Batch requests when possible
• Implement client-side request queuing

​

Handle 429 responses

import time

def generate_with_backoff(request_data, max_retries=3):
    for attempt in range(max_retries):
        response = api.generate(request_data)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            time.sleep(retry_after)
            continue

        return response

    raise Exception("Rate limit exceeded after retries")

​

Monitor usage

• Check X-RateLimit-Remaining header on responses
• Monitor usage in dashboard before month end
• Set up alerts for high usage