Rate Limits & Quotas

Overview

The PDFlys API enforces rate limits and monthly operation quotas to ensure fair usage and service stability. Your specific limits depend on your plan — view your current limits in the dashboard or check the pricing page for a plan comparison.

Response Headers

Every API response includes rate limit and usage information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1709125200
X-Usage-Current: 47
X-Usage-Limit: 500

Header	Description
X-RateLimit-Limit	Requests allowed per minute
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when the window resets
X-Usage-Current	Monthly operations used
X-Usage-Limit	Monthly operation limit for your plan

Handling Rate Limits

When you exceed the rate limit, the API returns 429 Too Many Requests:

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please retry after 12 seconds.",
    "retryAfter": 12
  }
}

Recommended Approach

async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = parseInt(
        response.headers.get("Retry-After") || "10"
      );
      await new Promise((r) => setTimeout(r, retryAfter * 1000));
      continue;
    }

    return response;
  }
  throw new Error("Max retries exceeded");
}

What Counts as an Operation

Every POST request to a processing endpoint counts as one operation, regardless of file size or processing time. These count:

• All PDF operations (POST /api/v1/*)
• Accessibility check (POST /api/v2/accessibility/check)
• Accessibility fix (POST /api/v2/accessibility/fix)

These do not count:

• GET requests (report retrieval, file listing, job polling)
• Report exports (PDF/CSV)
• Account management
• Health check

Monitoring Usage

Check your current usage via the Account API:

curl https://api.pdflys.com/api/v1/account/usage \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "current": 47,
  "limit": 500,
  "resetDate": "2026-03-01T00:00:00.000Z",
  "breakdown": [
    { "operation": "merge", "count": 15 },
    { "operation": "compress", "count": 12 },
    { "operation": "accessibilityCheck", "count": 10 }
  ]
}

Quota Exhaustion

When your monthly limit is reached, processing endpoints return 403 Forbidden:

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly operation limit reached. Upgrade your plan for more."
  }
}