API Rate Limits

The 5 tiers

Every request passes through five gates. The first one to deny wins.

Per-endpoint daily caps

Some endpoints have tighter limits because they consume significant CPU or GPU time:

File size limit

• 200 MB per file for the API (compared to 100 MB on the website).
• Some heavy AI tools have lower internal limits — e.g. upscale-image caps at 20 MB to keep GPU runs under 2 minutes.

Headers on every response

Every successful API response includes the following headers so you can track your quota without polling /api/v1/limits:

X-RateLimit-Limit-Day: 1000
X-RateLimit-Remaining-Day: 873
X-RateLimit-Reset-Day: 1775865600     # unix timestamp
X-RateLimit-Limit-Hour: 150
X-RateLimit-Remaining-Hour: 142
X-RateLimit-Limit-Endpoint: 50
X-RateLimit-Remaining-Endpoint: 38

What happens when you hit a limit

The API returns 429 Too Many Requests with a Retry-After header (in seconds) and an X-RateLimit-Reason header telling you which tier was hit:

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Reason: cooldown

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded (cooldown). Retry after 1 seconds.",
    "details": { "reason": "cooldown", "retry_after": 1 }
  }
}

Possible X-RateLimit-Reason values: cooldown, burst, hourly, daily, endpoint:<name>, banned.

Ban escalation

Repeated abuse triggers a temporary ban. Specifically: 10 rate-limit denials within 1 hour from the same IP → 24-hour ban with HTTP 403 Forbidden and error.code: BANNED.

If you think you've been banned unfairly (e.g. you share an IP with many users), contact us at /contact and we'll review.

Best practices to avoid throttling

• Sleep at least 1 second between consecutive requests (or use the Retry-After header on 429s).
• Use batch endpoints for bulk work: POST /api/v1/batch handles up to 20 files in a single HTTP call (each file still counts against your daily quota, but you save round trips).
• Watch the headers: when X-RateLimit-Remaining-Day drops below 100, slow down or cache your results.
• Inspect your usage at any time with GET /api/v1/limits — this endpoint does NOT count against your quota.
• Don't retry instantly on 429 — honour Retry-After. Instant retries can trigger ban escalation.

Need higher limits?

The current limits are MVP defaults. We're watching real usage and will adjust them based on demand. If you have a legitimate use case that needs higher quotas, get in touch via /contact.

A future paid tier may offer dedicated quotas, priority queues, and longer file retention — but the free tier will always remain.