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.

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.

Something unclear or missing on this page?