Rate Limiting

The API enforces several overlapping limits to ensure fair usage for all users. Limits apply per API key.

Default limits

Window	Quota units
Per minute	60 units
Per hour	1,000 units
Per day	10,000 units
Burst (per 10 seconds)	20 units

Request cost

Not all requests cost the same. Heavier operations consume more units:

Endpoint	Cost
POST /api/upload	10 units
DELETE /api/uploads/{slug}	3 units
All other endpoints	1 unit

Rate limit headers

Every successful response includes headers that let you track your remaining quota:

Header	Description
X-RateLimit-Limit	Your per-minute quota
X-RateLimit-Remaining	Units remaining in the current one-minute window
X-RateLimit-Reset	Unix timestamp when the current window resets
X-RateLimit-Cost	Units consumed by this specific request

Exceeding the limits

When a limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating the number of seconds to wait before retrying.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0

{
  "error": "Rate limit exceeded (per minute)."
}

Progressive slowdown behavior

When per-minute usage exceeds 80% of the quota, the API introduces a progressive response delay of up to 2 seconds. This acts as a warning before the hard 429 limit is hit, giving well-behaved clients a chance to slow down.

Best practices

• Read the X-RateLimit-Remaining header and slow down your request rate as it approaches zero.
• Implement retries with exponential backoff when you receive a 429.
• Use GET /api/uploads with pagination instead of many individual GET /api/uploads/{slug} requests.
• If your requirements call for higher limits, contact us via the contact page.