Rate Limiting

Intelligems uses a token bucket rate limiter for the external API.

Every successful response includes the following rate-limit headers:

• x-ratelimit-limit — bucket size for the endpoint

• x-ratelimit-remaining — remaining tokens in the current bucket

• x-ratelimit-reset — Unix timestamp in milliseconds at which the bucket next refills

Whether an error response carries them depends on how far the request got before failing. 400 validation failures do not. 404 and 429 do. A 401 carries them when the intelligems-access-token header was present but invalid — the limiter runs before the key is rejected, so an invalid key still consumes a token — and omits them when the header was missing or empty. Treat the headers as optional on any error response.

Typical limits in v25-10-beta:

• Experience list/detail/resource/timeseries endpoints: burst 50 (refill 25 every 30 seconds)

• Experience export endpoint: burst 20

• Sitewide analytics endpoints: burst 10 (refill 5 every 30 seconds)

• Custom events endpoint: burst 50 (refill 25 every 30 seconds)

Per-endpoint values are authoritative; always rely on the response headers for the active limit.

When a bucket is exhausted the API returns HTTP 429 with this body:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 12 seconds.",
  "retryAfter": 12
}

retryAfter is in seconds and may be absent if the limiter could not determine a reset time; the message string omits the retry clause in that case. A 429 response carries the rate-limit headers listed above, plus a standard retry-after header holding the same value as the retryAfter body field.