Quotas & rate limits

How billing periods, monthly caps, and rate limits work.

Two distinct mechanisms throttle traffic:

1. Monthly quota — a per-Organization cap aligned to your contractual billing period.
2. Rate limit — a short-window per-key burst limit.

Both surface as 429, with different codes and recovery semantics.

Monthly quota

Counted in billable requests since the start of your current billing period. The period boundaries come from your contract — typically the day of the month you signed up.

When exceeded:

HTTP/1.1 429 Too Many Requests
Retry-After: 1209600
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1715040000

{
  "title":  "Quota Exceeded",
  "status": 429,
  "code":   "QUOTA_EXCEEDED",
  "detail": "Monthly quota exceeded.",
  "limit": 10000,
  "used":  10000,
  "period_started_at": "2026-04-15T00:00:00Z",
  "period_ends_at":   "2026-05-15T00:00:00Z"
}

Recovery: wait until period_ends_at, or contact us to bump the cap.

Rate limit

Per-API-key burst protection. Short-window — typically tens of requests per second.

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 0

{
  "title":  "Rate Limit Exceeded",
  "status": 429,
  "code":   "RATE_LIMIT_EXCEEDED",
  "detail": "Rate limit exceeded."
}

Recovery: back off for Retry-After seconds and retry. Use exponential backoff with jitter on persistent 429s.

What counts as a billable request

Counts	Does not count
POST /v1/evaluate	GET /v1/sources
POST /v1/intersections	GET /v1/rulesets (list/get)
POST /v1/distance	POST /v1/rulesets (create)
POST /v1/subjects

Catalog reads and ruleset writes do not consume quota.