Rate Limits

Overview

All public API endpoints are rate-limited to protect service availability. There are two tiers depending on whether the endpoint requires authentication.

Rate Limits

Endpoint Type	Rate Limit	Tracked By
Authenticated public APIs	1,000 requests per minute	API key
Unauthenticated public APIs	60 requests per minute	IP address

• Authenticated endpoints require a valid API key. All authenticated public endpoints share a single 1,000/min budget per API key.

• Unauthenticated endpoints do not require an API key. They are rate-limited by the caller’s IP address at a stricter 60/min limit.

Authenticated Public API Endpoints (1,000/min)

These endpoints require an API key. Requests to any of them count toward the same 1,000/min budget for your key.

Category	Endpoint
Products	Brand Detail
Products	Product Detail
Products	Batch Detail
Products	Digital COA Detail
Collections	Item Details
Collections	Collection Details
Collections	Collection Cases Full Details
Collections	Inventory Collection Delete
Collections	Validate LucidIDs Existence
Collections	Case ID Add Items
Collections	Associate Regulator UID to Case ID
Inventory	Retail Transaction
Inventory	Package UIDs Associations Request
Inventory	Package UIDs Associations Fetch
Inventory	Get Package UID Export

Unauthenticated Public API Endpoints (60/min)

These endpoints do not require authentication and are rate-limited by IP address at a stricter rate.

Category	Endpoint
Collections	LucidID Inventory Collection Lookup
Collections	LucidID Inventory Regulator UID Lookup

What Happens When You Hit the Limit

When you exceed the rate limit, the API responds with:

• HTTP Status: 429 Too Many Requests

• Response Body: {"detail": "Request was throttled. Expected available in X seconds."}

• Header: Retry-After: <seconds> – the number of seconds to wait before your next request will be accepted

Handling Rate Limits

1. Check the Retry-After header: When you receive a 429 response, read the Retry-After header value and wait that many seconds before retrying.

2. Implement exponential backoff: As a fallback, use exponential backoff starting at 1 second and doubling on each consecutive 429, up to a maximum of 60 seconds.

3. Spread requests over time: Avoid sending all requests in a single burst. Distributing requests evenly across the one-minute window reduces the chance of hitting the limit.

4. Batch where possible: If you need to look up many items, prefer bulk/list endpoints over making individual requests per item.

5. Cache responses: Cache responses for data that does not change frequently (e.g., brand or product details) to avoid redundant API calls.

Limitations

• Shared budget across endpoints: All authenticated public endpoints share the same 1,000/min allowance. There is no per-endpoint rate limit.

• No per-key customization: All API keys have the same rate limit. Custom rate limits for individual integrations are not currently available.

• Burst-friendly window: The rate limiter uses a sliding window, meaning it is possible to send all 1,000 requests at once. However, doing so will exhaust your budget and block subsequent requests until the window advances.

• Shared IP budget for unauthenticated endpoints: If multiple clients share the same public IP (e.g., behind a corporate proxy or NAT), they will share the 60/min budget.

Need a Higher Limit?

If your integration requires a higher rate limit, contact LucidGreen support with details about your use case and expected request volume.