Html2pdf API Rate Limits: Per-Minute Handling Guide

Html2pdf API rate limits specify how many requests your application can send per minute, and handling them correctly means implementing retry logic with exponential backoff and respecting the Retry-After header. This article explains what these limits are, why they exist, and concrete strategies to avoid hitting them or to recover gracefully when you do.

Formula

The core relationship is simple: Usage (%) = (Requests per minute / API limit) × 100. The variable requests is the number of API calls you make in a given minute, and limit is the maximum allowed by your plan (often 60, 120, or 300). The remaining capacity is simply limit - requests. This calculator helps you visualize your current consumption and plan your batch jobs accordingly.

Worked Example

Using the defaults: if your API limit is 60 requests per minute and you send 60 requests, your usage is (60 / 60) × 100 = 100%, and remaining is 0. If you send 30 requests, usage is 50% and remaining is 30. This shows you exactly how close you are to the threshold.

Background: Why Rate Limits Exist

API providers, including html2pdf services, impose rate limits to protect their infrastructure from overload and to ensure fair usage among all clients. Without limits, a single user could monopolize server resources, causing slow responses or outages for others. Limits are typically expressed as requests per second (RPS) or per minute (RPM). For html2pdf APIs, the limit often depends on your subscription tier—free tiers might allow 20–60 requests per minute, while paid plans offer higher thresholds. Some providers also enforce daily or monthly caps, so monitor both short-term and long-term quotas.

How Rate Limits Are Enforced

When you exceed the limit, the API responds with HTTP status code 429 Too Many Requests. The response usually includes a Retry-After header indicating the number of seconds to wait before retrying. Some APIs also return a JSON body with details like error.code and error.message. Your client code should check for these signals and react accordingly. Additionally, many APIs provide response headers such as X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset to help you track your usage in real time.

How to Choose a Handling Strategy

Your approach depends on your application type. For batch jobs that convert many HTML files to PDF, you can pre-calculate the number of requests and schedule them within the limit. For real-time user requests, you need a more dynamic solution. Here are common strategies:

• Exponential backoff: On a 429 response, wait an initial interval (e.g., 1 second), then double the wait time with each retry (1s, 2s, 4s, 8s) up to a maximum (e.g., 60s). Always respect the Retry-After header if present.
• Queueing: Place requests in a queue and process them at a rate that stays below the limit (e.g., one request every 1.1 seconds for a 60 RPM limit). This smooths out bursts.
• Throttling: Use a token bucket algorithm in your code to limit the outgoing request rate to a safe level, preventing 429s before they happen.
• Batching: If the API supports it, combine multiple documents into a single request (e.g., merging HTML files into one PDF) to reduce the number of calls.

Common Problems and Misconceptions

A frequent mistake is assuming that the rate limit is per IP address rather than per API key. Most html2pdf services track usage by API key, so if you share a key across multiple servers, you share the limit. Another misconception is that retrying immediately after a 429 will work—it usually makes things worse. Always wait for the specified retry time. Also, some developers forget to handle the case where the API returns a 429 with a Retry-After of 0, which can cause a tight loop; add a minimum delay of at least 100ms. Finally, note that limits can change based on server load; some APIs dynamically adjust limits during peak times, so even if you are under the nominal limit, you might still get a 429.

Costs and Plan Considerations

Higher rate limits generally come with higher subscription costs. Free tiers are great for testing but often have low RPM limits and include branding on generated PDFs. Paid plans offer more headroom, but you should still implement retry logic because even premium plans have limits. Some providers offer burstable limits—you can exceed the average for short periods, but sustained overuse will be throttled. Always check the provider’s documentation for the exact limits of your plan, as they can change. If you need to process a large volume, consider negotiating a custom plan or using an on-premises solution where no external rate limit applies.

Safety and Best Practices

To avoid unexpected failures, always wrap your API calls in a function that handles 429 errors, network timeouts, and other transient issues. Log the rate limit headers to monitor your usage. Implement a circuit breaker: if you get multiple 429s in a row, pause all requests for a longer period. Also, ensure that your retry logic does not cause duplicate conversions—if a request succeeds but the response is lost, you might create duplicate PDFs; use idempotency keys if the API supports them. Finally, test your application under simulated rate limits to verify that your handling works correctly.

Alternatives to a Third-Party API

If rate limits are a constant problem, consider alternatives: run a local HTML-to-PDF converter like headless Chrome (via Puppeteer) or wkhtmltopdf. These tools have no API rate limits, but they require server resources and maintenance. Another option is to use a different API provider with higher limits or a pay-per-use model. Some providers offer dedicated servers or private instances with no shared rate limits. Evaluate your volume and latency requirements before switching, as self-hosting may not be cost-effective for low volumes.

Frequently Asked Questions

What exactly is a 429 Too Many Requests error? It’s an HTTP status code that the API returns when you exceed the allowed number of requests in a given time window. The response typically includes a Retry-After header telling you how many seconds to wait before trying again.

How do I find out my current rate limit? Check your API provider’s dashboard or documentation. Many providers also return rate limit information in response headers, such as X-RateLimit-Limit and X-RateLimit-Remaining.

Can I increase my rate limit without upgrading my plan? Generally no, but some providers allow you to purchase temporary bursts or add-on packs. Contact your provider’s support to discuss your needs.

What happens if I ignore rate limits? Your requests will fail with 429 errors, and repeated violations may lead to temporary or permanent suspension of your API key. It’s best to implement proper handling.

Is it better to use a queue or retry with backoff? For predictable batch jobs, a queue is more efficient. For real-time requests, retry with exponential backoff is simpler. Many production systems use both: a queue to smooth out load and backoff to handle occasional spikes.

Do rate limits apply to each API key or each IP address? Most html2pdf APIs track usage per API key. If you have multiple servers, they share the same limit unless you use separate keys for each server.

Related

• Multi Window on Samsung Galaxy J7: A How-To
• Fix Android Not Registered on Network
• Clean Windows Without Water: Methods That Work

in requests | Requests per minute | - | 60 | 1 | 100000
in limit | Your API limit | - | 60 | 1 | 100000
out pct | Usage % | % | requests / limit * 100 | 1
out remaining | Remaining requests | - | max(0, limit - requests) | 0