Rate limits
Per-key buckets, per-UID buckets, plan limits, response headers, and how `Retry-After` works.
Rate limits
gpdf-api uses a token-bucket rate limiter, per API key.
Limits by plan
| Plan | Steady rate | Burst | Notes |
|---|---|---|---|
| Free | 10 r/s | 20 | Per key. |
| Pro | 20 r/s | 40 | Per key. |
| Self-host | unlimited | unlimited | The bucket is enforced by your own infra, not us. |
A burst is the number of tokens the bucket holds at full. So a Pro key can do 40 requests instantly, then settles to 20 r/s.
Headers
Every response (success or 429) includes:
X-GPDF-RateLimit-Limit: 40
X-GPDF-RateLimit-Remaining: 37
X-GPDF-RateLimit-Reset: 1714234567
The values above show a Pro key (burst = 40). Free is Limit: 20, Self-host omits the headers entirely.
| Header | Notes |
|---|---|
X-GPDF-RateLimit-Limit |
Tokens at full bucket. |
X-GPDF-RateLimit-Remaining |
Tokens left right now. |
X-GPDF-RateLimit-Reset |
Unix timestamp when the bucket will be full again. |
On 429, additionally:
Retry-After: 1
Retry-After is in seconds. Some clients (Node fetch recent versions) parse it automatically; others, you have to read manually.
Recommended client behaviour
async function renderWithRetry(req, attempts = 4) {
let backoff = 200
for (let i = 0; i < attempts; i++) {
const res = await fetch(url, { method: 'POST', headers, body })
if (res.status === 429) {
const retryAfter = Number(res.headers.get('retry-after') ?? 1) * 1000
await sleep(Math.max(retryAfter, backoff))
backoff *= 2
continue
}
if (res.ok) return res
if (res.status >= 500) {
await sleep(backoff)
backoff *= 2
continue
}
throw new Error(`${res.status}: ${await res.text()}`)
}
throw new Error(`exceeded ${attempts} attempts`)
}
Don't:
- Retry tighter than
Retry-After. It won't be ready and you'll burn requests. - Spread one workload across multiple keys. The quota is per account, not per key. You'll just confuse your own logs.
- Treat 4xx (except 429) as retryable. They will not become 200 by trying again. Fix the request.
What's inside the bucket
The per-key token bucket only applies to authenticated render endpoints — primarily POST /v1/pdf. GET /health doesn't carry an API key and is not rate-limited at the application layer; abuse is handled upstream by Cloud Run / our edge infrastructure.
What about a global anti-abuse limit?
There is no per-IP cap enforced in application code. Any global throttling is applied by the underlying Cloud Run / load-balancer layer and is intentionally undocumented. If you have a workload that needs sustained high throughput, contact us before scaling up.
Self-host
The binary doesn't enforce anything by default. Use your reverse proxy (nginx, Cloud Run, Caddy) to apply whatever bucket fits your workload. The same X-GPDF-RateLimit-* headers are not set in self-host mode.
Related
- Errors →
rate_limited - Authentication → — keys & rotation.
- Performance → — making fewer requests is the best rate-limit fix.
Something unclear or missing on this page?