Rate limits

Every request against an API key is counted twice: once in a per-minute bucket and once in a per-day bucket. Exceeding either returns 429.

Your limits

curl https://api.mageran.ai/api/v1/balance \
  --header 'x-mager-api-key: YOUR_API_KEY'

"rateLimit": {
  "perMinute": 60,
  "perDay": 5000,
  "accountPerMinute": 60,
  "accountPerDay": 5000
}

• perMinute / perDay are the limits applied to the key you used.
• accountPerMinute / accountPerDay are the account defaults. A key inherits these unless it carries its own override.

How counting works

Buckets are fixed windows, not sliding ones. The minute bucket resets on the minute; the day bucket resets at UTC midnight. A burst at 10:00:59 and another at 10:01:00 land in different buckets.

Every authenticated request counts, including GET /balance and every poll of a task. Polling a task once a second for two minutes spends 120 requests on one generation.

Handling 429

{
  "error": {
    "statusCode": 429,
    "message": "Rate limit exceeded"
  }
}

The response does not carry a Retry-After header, so back off on your own:

1. Wait, then retry with exponential backoff and jitter — start around one second, cap at a minute.
2. Do not retry immediately in a loop. A tight retry loop keeps you rate-limited.
3. If you hit the daily limit, backoff will not help. Queue the work and resume tomorrow, or ask for a higher limit.

Staying under

• Use webhooks instead of polling. One callback replaces dozens of GET requests.
• Poll every 3–5 seconds, not continuously.
• Cache GET /models and GET /templates. They change rarely; there is no reason to fetch them per user action.
• Use separate keys for separate workloads, each with its own limit, so a batch job cannot starve your interactive traffic.

Need more headroom? Limits are per key and per account, and both can be raised. Ask through the dashboard.