In a Nutshell
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.Max 100MB payload size
Our server cuts the connection and returns an error if the request content length exceeds 100MB.
Time-out
Any request that takes more than 5 seconds will be aborted by our server.
2 months events retention
Events (webhooks) are kept for up to 2 months, whether delivered or not.
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.
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.
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. |
These limits values may be changed without prior notice, as long as they become higher (i.e. more lenient).
Avoiding Rate Limits Proactively
- Batch where possible. Use the
?include=embeddedfeature 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 for real-time notifications. This dramatically reduces your request volume.
- Cache responses. Use HTTP ETags and conditional requests to avoid re-fetching unchanged resources.
- Paginate consciously. Use the
limitparameter 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.