---
title: Rate limits | Lightfield
description: Understand the rate limits applied to Lightfield API requests.
---

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.