Rate Limits
pdfRelay enforces rate limits to ensure fair usage and maintain reliability for all users. Limits vary by plan tier.
Per-Tier Rate Limits
Rate limits are applied per API key on a sliding window basis:
| Plan | Requests / minute | Requests / hour | Monthly quota |
|---|---|---|---|
| Free | 5 | 30 | 10 conversions |
| Starter | 20 | 200 | 500 conversions |
| Growth | 60 | 1,000 | 5,000 conversions |
| Scale | 200 | 5,000 | 25,000 conversions |
| Enterprise | Custom | Custom | Unlimited |
Rate Limit Headers
Every API response includes headers indicating your current rate limit status:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum number of requests allowed per minute |
X-RateLimit-Remaining | Number of requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp when the rate limit window resets |
Retry-After | Seconds to wait before retrying (only included on 429 responses) |
Example response headers:
HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1705312260
Content-Type: application/pdfHandling Rate Limit Errors
When you exceed the rate limit, the API returns a 429 Too Many Requests response:
{
"success": false,
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Try again in 8 seconds.",
"details": {
"limit": 60,
"remaining": 0,
"reset_at": "2025-01-15T10:31:00Z",
"retry_after": 8
}
}
}Best Practices
- Monitor rate limit headers on every response to proactively throttle your requests before hitting the limit.
- Implement exponential backoff when you receive a 429 response. Respect the
Retry-Afterheader. - Use the Batch API to convert multiple documents in a single request. A batch with 50 items counts as 1 request against the rate limit (but 50 against your monthly quota).
- Use async conversions for large documents. They are processed in the background and do not block your rate limit window.
- Queue requests on your side if you anticipate bursts. Spread requests evenly rather than sending them all at once.
- Upgrade your plan if you consistently hit rate limits. Higher tiers offer significantly higher limits.