Rate Limiting¶

The API enforces rate limits to protect platform stability. Limits are applied per OAuth2 application.

How It Works¶

Application-Level Rate Limit¶

Every OAuth2 application has a configurable rate limit. This is a global bucket -- all requests to any endpoint count toward the same limit.

View-Level Rate Limit¶

Some endpoints enforce a stricter per-endpoint limit in addition to the application-level limit. When configured, each (application, endpoint) pair gets its own counter. Both limits must pass for a request to succeed.

Response Headers¶

Every response includes rate-limit headers reflecting the most constrained active limit:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Seconds until the window resets

Rate Limit Exceeded (429)¶

When the rate limit is exceeded, the API responds with HTTP 429 and a Retry-After header:

{
  "errors": [
    {
      "status": "429",
      "detail": "Request was throttled. Expected available in 42 seconds.",
      "source": {"pointer": "/data"}
    }
  ]
}

Headers on 429 responses:

Retry-After: 42
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 42

Best Practices¶

Monitor headers: check X-RateLimit-Remaining to throttle requests client-side before hitting the limit
Respect Retry-After: always wait the indicated time before retrying after a 429
Exponential backoff: use exponential backoff when retrying after rate-limit errors
Request only what you need: use pagination with reasonable page sizes and filter results to reduce the number of API calls