Rate limits

Rate limits apply per API key and combine a per-minute burst limit with a per-month quota. Hitting the per-minute limit returns 429 rate_limit_exceeded; exhausting the monthly quota on a write or AI request returns 429 monthly_quota_exceeded. Both carry a Retry-After header.

Limits by plan

| Plan | Per minute | Per month | Notes | |---|---|---|---| | Free | 60 | 1,000 | Read API only | | Starter | 300 | 10,000 | Read + write | | Pro | 1,500 read / 600 write | 100,000 | Full API | | Enterprise | Custom | Custom | Negotiated per contract |

Per-minute caps are scoped by tier, read and write each get their own window. Free and Starter share a single per-minute figure across both tiers; Pro splits them (1,500 read, 600 write).

Per-minute uses a sliding window resetting every 60 seconds. Per-month resets on the 1st of each calendar month, UTC, not your billing renewal date.

Multiple keys on one org each get their own burst limit but share the monthly quota.

Response headers

Every response, success or failure, includes:

| Header | Meaning | |---|---| | X-RateLimit-Limit | Total requests allowed in the current per-minute window | | X-RateLimit-Remaining | Requests left before the per-minute limit triggers | | X-RateLimit-Reset | Unix timestamp (seconds) when the per-minute window resets | | X-Monthly-Quota-Limit | Monthly request quota for the plan | | X-Monthly-Quota-Used | Requests counted against the monthly quota so far this period | | X-Monthly-Quota-Reset | Unix timestamp (seconds) when the monthly quota resets (1st of next month, UTC) | | X-Monthly-Quota-Exceeded | true on read responses served after the monthly quota is hit. You're still served, but you've passed your quota, upgrade or wait for the reset. | | Retry-After | Seconds to wait before retrying. Present only on 429 responses. |

429 response shape

A per-minute burst limit returns rate_limit_exceeded:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please try again later.",
    "retryAfter": 42
  }
}

A monthly quota limit (on write or AI tiers) returns monthly_quota_exceeded:

{
  "error": {
    "code": "monthly_quota_exceeded",
    "message": "Monthly API request quota exceeded. STARTER plan allows 10000 requests/month. Resets at 2026-07-01T00:00:00.000Z.",
    "limit": 10000,
    "used": 10000,
    "resetAt": "2026-07-01T00:00:00.000Z",
    "upgradeUrl": "https://thefaq.app/pricing"
  }
}

Branch your retry logic on the code. A rate_limit_exceeded means wait retryAfter seconds and try again. A monthly_quota_exceeded means upgrade or wait until resetAt, days, not seconds. Read requests are never blocked by the monthly quota; they keep serving with the X-Monthly-Quota-Exceeded: true header instead.

Staying within limits

Cache reads. Question lists and search results change far less than read traffic. The @faqapp/core SDK has built-in caching with configurable TTL. For your own stack, cache responses by the URL + auth-key pair.

Paginate with cursors, not by fetching everything. Use cursor from meta.pagination to walk through pages on demand. Don't fan out parallel requests for every page; that hits the burst limit fast.

Batch writes when you can. If you have 50 questions to import, send them as a single create-many request rather than 50 sequential POSTs.

Watch x-ratelimit-remaining. When it drops below ~20% of x-ratelimit-limit, slow down. Most rate-limiting incidents are visible 10–30 seconds before they hit.

Back off exponentially on repeated 429s. Start with the Retry-After value; on the second 429 double it; cap at ~60s. The SDK does this automatically.

Separate read and write keys. Burst spikes on read traffic shouldn't block your write workload. Two keys, two separate per-minute windows.