Rate limits

Authenticated API requests use separate per-workspace buckets. The default limits are:

Category	Method(s)	Limit
Write	Create, Update, Delete	25 requests per second
Sustained write	Create, Update, Delete	7,500 requests, refilled evenly over 10 min
Read	Retrieve, Definitions	25 requests per second
Search	List	25 requests per second
Sequence tests	Start a sequence test	5 requests per minute

Every write counts against both write limits. A long bulk job running at 25 writes per second uses up the sustained allowance after about 10 minutes, then gets about 12 writes per second. Both limits return 429, and the headers describe whichever one rejected the request.

These limits may change. If you need higher throughput, reach out to the Lightfield team.

Rate limit headers

Responses that reach the workspace rate limiter include these headers when available. Authentication failures, public endpoints and capacity rejections (503) may omit them; clients must handle missing headers.

Header	Description
X-RateLimit-Limit	Capacity of the applicable bucket
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: 25
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1741392001

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

When the API as a whole is at capacity, it returns 503 service_unavailable instead of 429, also with a Retry-After header. Handle it the same way.

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. Stop after a bounded number of attempts. For writes, check idempotency support before retrying and reuse the original key where supported.
• 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.