Rate Limits

The DoCreate API enforces rate limits to ensure fair usage and platform stability. Each plan includes a monthly PDF generation quota and per-minute request limits.

Limits by Plan

Monthly quotas reset on the first day of each calendar month at 00:00 UTC.

Rate Limit Headers

Every API response includes headers that indicate your current rate limit status:

Example response headers:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4832
X-RateLimit-Reset: 1740787200

What Happens When You Exceed the Limit

When you exceed your monthly quota or per-minute rate limit, the API returns a 429 Too Many Requests response:

{
  "error": "Rate limit exceeded. Please wait before making another request.",
  "code": "RATE_LIMITED"
}

The response includes a Retry-After header indicating how many seconds to wait before retrying.

Monthly Quota Exceeded

If you have used all PDFs in your monthly quota, every subsequent request will return 429 until the quota resets at the start of the next month. You can upgrade your plan at any time through the Dashboard to immediately increase your quota.

Per-Minute Rate Limit Exceeded

If you exceed the per-minute request limit, the API will throttle your requests temporarily. The Retry-After header tells you exactly how long to wait. This limit resets automatically within 60 seconds.

Monitoring Your Usage

You can track your current usage at any time by inspecting the rate limit headers on any API response, or by visiting the Usage section in your Dashboard.

Programmatic Usage Check

Read the rate limit headers from any successful response:

const response = await fetch('https://api.docreate.io/api/pdf/external', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ html: '<h1>Hello</h1>' }),
});

const limit = response.headers.get('X-RateLimit-Limit');
const remaining = response.headers.get('X-RateLimit-Remaining');
const resetTimestamp = response.headers.get('X-RateLimit-Reset');
const resetDate = new Date(parseInt(resetTimestamp, 10) * 1000);

console.log(`Usage: ${limit - remaining} / ${limit} PDFs`);
console.log(`Resets: ${resetDate.toISOString()}`);

Handling Rate Limits Gracefully

Implement rate-limit-aware logic in your application to avoid disruptions:

async function generatePdf(payload) {
  const response = await fetch('https://api.docreate.io/api/pdf/external', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(payload),
  });

  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get('Retry-After'), 10) || 60;
    console.warn(`Rate limited. Retrying in ${retryAfter} seconds.`);
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
    return generatePdf(payload); // Retry the request
  }

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API error: ${error.error}`);
  }

  return Buffer.from(await response.arrayBuffer());
}

Best Practices

• Queue PDF generation requests instead of firing them all at once. Use a job queue to stay within per-minute limits.
• Cache generated PDFs when the same document is requested multiple times. Store results and serve from cache to avoid unnecessary API calls.
• Monitor usage proactively by checking X-RateLimit-Remaining and alerting when usage approaches the quota.
• Upgrade before hitting limits. If you consistently approach your monthly quota, consider upgrading to a higher plan to avoid service interruptions.
• Use bulk generation wisely. If you need to generate many PDFs at once, spread requests evenly over time rather than sending them in a burst.