Rate limits

The Lightfield API enforces rate limits to ensure fair usage and platform stability. During this early launch period, the following limits apply per organization:

Category	Method(s)	Limit
Write	Create, Update	25 requests per second
Read	Retrieve, Definitions	25 requests per second
Search	List	25 requests per second

These limits are subject to change as the platform scales. If you need higher throughput, reach out to the Lightfield team.

Rate limit headers

Every API response includes headers to help you track your current usage:

Header	Description
X-RateLimit-Limit	Maximum requests allowed per second (bucket capacity)
X-RateLimit-Remaining	Number of requests remaining in the current window
X-RateLimit-Reset	Unix timestamp (seconds) when the bucket will be fully replenished

Handling rate limit errors

When you exceed the rate limit, the API responds with HTTP status 429 Too Many Requests. The response includes a Retry-After header indicating how many seconds to wait before retrying.

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

{
  "type": "too_many_requests",
  "message": "Rate limit exceeded. Please try again later."
}

Best practices

• Implement exponential backoff — When you receive a 429, wait for the duration specified in Retry-After, then retry with increasing delays on consecutive failures.
• Monitor rate limit headers — Check X-RateLimit-Remaining proactively to throttle your requests before hitting the limit.
• Cache reads — Avoid redundant GET requests by caching responses on your end when the data doesn’t change frequently.