Skip to main content
This page covers the request limits Lumos enforces on its public API at https://api.lumos.com, the response you get when you exceed them, and how to retry. For authentication and token setup, see Build and Extend with Lumos.

​
Current limits

Both limits apply at the same time. A request that would exceed either one is rejected.
  • Counted per organization. Every API token in your Lumos organization shares one count. Creating more tokens doesn’t raise the limit.
  • Shared across endpoints. Every endpoint draws from the same count. There are no separate per-endpoint limits.
  • Moving window. Lumos counts the requests made in the last second and the last minute, not since a fixed reset time. A burst stays counted for the full window after it happens.
  • Subject to change. Lumos can adjust these values. Read the rate limit headers on each response instead of hardcoding the numbers.
Requests that don’t use a Lumos API token (prefixed lsk_) are counted per credential.

​
Rate limit headers

Lumos returns these headers so your client can track its usage. On successful responses, these headers describe the 1-second window, so they don’t show how much of the per-minute limit you’ve used. On a 429 response, the headers describe the window you exceeded.

​
When you exceed a limit

Lumos rejects the request with 429 Too Many Requests and doesn’t process it. The response body depends on the endpoint. /v1 endpoints return the standard error envelope, with type and code set to rate_limited.
Other endpoints, such as /appstore/apps, return a single error string.
SCIM endpoints under /scim/v2 return an error in the SCIM error schema (RFC 7644).

​
How to back off

  1. Stop sending requests when you receive a 429.
  2. Wait the number of seconds in the Retry-After header, then retry the request.
  3. Pace long-running jobs to stay under 4,000 requests per minute. X-RateLimit-Remaining on successful responses only tracks the 1-second window.
  4. If a response has no Retry-After header, retry with exponential backoff and random jitter.
Because the count is shared across your organization, scripts and tools run by different teams draw from the same limit. Spread large jobs, such as bulk exports, over time instead of running them in parallel.