Image Conversion API Rate Limits — What You Need to Know

Rate limits protect the API from abuse and ensure fair usage for everyone. Understanding how they work helps you build applications that handle them gracefully instead of breaking unexpectedly.

Current Rate Limits

These limits apply per API key (authenticated) or per IP address (anonymous).

How to Check Your Usage

Every API response includes rate limit headers:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 27
X-RateLimit-Reset: 1706745600

• Limit: Your per-minute allocation
• Remaining: How many requests you have left in this window
• Reset: Unix timestamp when the window resets

Handling 429 (Too Many Requests)

When you exceed the limit, the API returns HTTP 429:

{
  "error": "Rate limit exceeded",
  "retry_after": 12
}

The retry_after field tells you how many seconds to wait. Implement exponential backoff:

import time
import requests

def convert_with_retry(file_path, api_key, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            "https://koalapic.com/api/v1/convert",
            headers={"Authorization": f"Bearer {api_key}"},
            files={"file": open(file_path, "rb")},
            data={"output_format": "webp"},
        )

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
            print(f"Rate limited. Retrying in {retry_after}s...")
            time.sleep(retry_after)
            continue

        return response.json()

    raise Exception("Max retries exceeded")

The Escalation System

KoalaPic uses a 5-tier escalation system for repeated rate limit violations:

1. Tier 1: Standard 429 response with retry_after
2. Tier 2: Extended cooldown (5 minutes)
3. Tier 3: 1-hour temporary block
4. Tier 4: 24-hour block with email notification
5. Tier 5: Automatic key suspension (requires manual reactivation)

The system is designed to be forgiving for occasional bursts while preventing sustained abuse.

Best Practices

1. Check headers proactively: Don’t wait for a 429. If Remaining is low, slow down.
2. Use batch endpoints: One batch request for 50 images is better than 50 individual requests.
3. Cache results: Don’t re-convert the same image. Store download URLs (they’re valid for 1 hour).
4. Use webhooks: For async workflows, submit the request and let KoalaPic notify you when it’s done — no polling needed.

Download Rate Limits

Downloaded files have separate limits:

• Per IP: 30 downloads per minute
• Per token: 10 downloads per token lifetime (2-hour TTL)

These are independent of API conversion limits.

Monitoring Your Usage

Check your current usage and limits in the dashboard. The usage page shows:

• Requests today vs daily limit
• Rate limit hits in the last 24 hours
• Escalation tier (if applicable)

Next Steps

• Check your limits in the dashboard
• Read the full API documentation for all endpoints
• Set up batch conversion to use your quota efficiently