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, or the bulk converter for up to 50 URLs at a time.
• 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. Current quotas and the live headers are documented in the API reference, and the API status page shows whether limits are being applied unusually.