Rate Limits

The PageGun API enforces rate limits to ensure fair usage and platform stability.

Default Limits

Scope	Limit
Per API key	100 requests / minute

Limits apply across all endpoints. Publishing operations count as a single request.

Rate Limit Headers

Every API response includes rate limit information:

Header	Description
`x-ratelimit-limit`	Maximum requests per window
`x-ratelimit-remaining`	Requests remaining in current window
`x-ratelimit-reset`	Unix timestamp when the window resets

Example response headers:

x-ratelimit-limit: 100
x-ratelimit-remaining: 87
x-ratelimit-reset: 1700000060

429 Too Many Requests

When you exceed the rate limit, the API returns:

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after 23 seconds."
  }
}

The Retry-After header indicates how many seconds to wait.

Best Practices

Exponential Backoff

When you receive a 429, retry with exponential backoff:

async function apiWithRetry(fn: () => Promise<Response>, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fn()
    if (res.status !== 429) return res

    const retryAfter = parseInt(res.headers.get('Retry-After') || '1')
    const delay = retryAfter * 1000 * Math.pow(2, i)
    await new Promise(r => setTimeout(r, delay))
  }
  throw new Error('Rate limit exceeded after retries')
}

Reduce Request Volume

Batch your work: Update multiple pages, then publish them in sequence.
Cache responses: Don't re-fetch data you already have.
Use webhooks (coming soon) instead of polling for changes.

Monitor Your Usage

Check x-ratelimit-remaining before making burst requests. If you're running low, slow down proactively.