API rate limits explained

KoalaPic uses rate limiting to ensure fair access for all users.

Rate limit tiers

How it works

Every API response includes rate limit headers:

• X-RateLimit-Limit-Minute — Your per-minute quota
• X-RateLimit-Remaining-Minute — Requests remaining this minute
• X-RateLimit-Limit-Day — Your daily quota
• X-RateLimit-Remaining-Day — Requests remaining today
• Retry-After — Seconds to wait (only on 429 responses)

What happens when you exceed limits

1. First offense: You get a 429 Too Many Requests response with a Retry-After header.
2. Repeated violations: Temporary blocks escalate from 1 minute to 5 minutes to 15 minutes.
3. Persistent abuse: Automatic 24-hour ban.

Tips to avoid rate limits

• Use webhooks instead of polling — you’ll get notified when conversions complete.
• Batch your requests using the batch conversion endpoint.
• Cache results — don’t re-convert the same file.
• Use an API key — it gives you 3x the anonymous limit.

Download limits

Downloads have separate limits: 30 per minute per IP and 10 per token lifetime (2-hour TTL). These prevent abuse of the download endpoints specifically.