Rate Limits

Rate limits protect the API from abuse and ensure fair access for all users.

Limits by Plan

Plan	Requests/Day	Requests/Minute	Burst
Free	1,000	10	20
Pro	50,000	100	200
Business	200,000	500	1,000
Enterprise	Custom	Custom	Custom

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 842
X-RateLimit-Reset: 1709856000

Header	Description
`X-RateLimit-Limit`	Total requests allowed per day
`X-RateLimit-Remaining`	Requests remaining today
`X-RateLimit-Reset`	Unix timestamp when limit resets

Handling Rate Limits

When you exceed your rate limit, the API returns 429 Too Many Requests:

{
  "_tag": "RateLimitExceeded",
  "message": "Rate limit exceeded. Retry after 60 seconds.",
  "retryAfter": 60
}

The Retry-After header indicates when you can retry.

Best Practices

Use caching

Cache responses when possible. Card data and set information change infrequently.

// Example: Cache card data for 1 hour
const card = await cache.get(`card:${id}`)
  ?? await pulls.cards.get(id).then(c => {
    cache.set(`card:${id}`, c, { ttl: 3600 })
    return c
  })

Batch requests

Use bulk endpoints instead of making individual requests:

// Bad: 100 requests
for (const id of cardIds) {
  await pulls.cards.get(id)
}

// Good: 1 request
const cards = await pulls.cards.list({ ids: cardIds })

Implement exponential backoff

async function fetchWithRetry(fn: () => Promise<T>, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn()
    } catch (e) {
      if (e.status === 429) {
        const delay = Math.pow(2, i) * 1000
        await new Promise(r => setTimeout(r, delay))
      } else {
        throw e
      }
    }
  }
}

Checking Usage

Query your current usage via the /v1/usage endpoint:

curl -H "Authorization: Bearer pk_live_..." \
  https://api.pulls.app/v1/usage

{
  "plan": "pro",
  "period": {
    "start": "2024-03-01T00:00:00Z",
    "end": "2024-03-31T23:59:59Z"
  },
  "requests": {
    "used": 12500,
    "limit": 50000,
    "remaining": 37500
  }
}