> ## Documentation Index
> Fetch the complete documentation index at: https://developers.luccasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Limits

> To maintain consistent response times for all users, limits are placed on how the Lucca API can be consumed.

## In a Nutshell

<CardGroup>
  <Card title="Max 50 requests / min per tenant.">
    Otherwise you'll get a `429 Too Many Requests`. Note: a "tenant" is a Lucca domain, e.g. `mycompany.ilucca.net`.
    This means that all your integrations share the same limit, but a test or sandbox environment on a different domain
    will have its own separate limit.
  </Card>

  <Card title="Max 100MB payload size">
    Our server cuts the connection and returns an error if the request content length exceeds 100MB.
  </Card>

  <Card title="Time-out">
    Any request that takes more than 5 seconds will be aborted by our server.
  </Card>

  <Card title="2 months events retention">
    Events (webhooks) are kept for up to 2 months, whether delivered or not.
  </Card>

  <Card title="3 seconds timeout on webhooks">
    Events are sent to webhook-endpoints through POST requests that have a 3 seconds timeout. If there are retry attempts left, then the event will be planned for a retry later.
  </Card>

  <Card title="Up to 5 delivery attempts">
    Failed event deliveries are retried up to 4 times (so, at most, 5 delivery attempts total) over \~24 hours after the initial attempt. Keep in mind you can always trigger additional manual retries.
  </Card>
</CardGroup>

***

## Errors Due to Limits Exceeded

Your integrations may encounter errors due to server limits being exceeded.

| HTTP Status | Retry?                     | Notes                                        |
| :---------- | :------------------------- | :------------------------------------------- |
| `408`       | ✅ Yes (simplified request) | Request timeout — possibly too complex.      |
| `429`       | ✅ Yes (later)              | Rate limit exceeded — respect `Retry-After`. |
| `500`       | ✅ Maybe                    | Unexpected server error.                     |
| `503`       | ✅ Yes                      | Service temporarily unavailable.             |
| `400`       | ❌ No                       | Client-side error — fix the request.         |
| `401`       | ❌ No                       | Refresh your access token first, then retry. |
| `403`       | ❌ No                       | Check your OAuth scopes.                     |
| `404`       | ❌ No                       | Resource does not exist or is inaccessible.  |

<Info>
  These limits values may be changed without prior notice, as long as they become higher (i.e. more lenient).
</Info>

***

## Avoiding Rate Limits Proactively

* **Batch where possible.** Use the `?include=embedded` feature to retrieve related resources in a single request instead of N+1 queries.
* **Use webhooks instead of polling.** Rather than repeatedly calling GET endpoints to detect changes, subscribe to the relevant [webhook events](../webhooks) for real-time notifications. This dramatically reduces your request volume.
* **Cache responses.** Use [HTTP ETags and conditional requests](./cache) to avoid re-fetching unchanged resources.
* **Paginate consciously.** Use the `limit` parameter to retrieve as much data as needed in each page — but not more. Unnecessary data fetching wastes your rate limit quota.
* **Parallelize carefully.** Avoid spawning unbounded parallel requests. Implement a request queue with a concurrency limit.