Rate Limiting

Learn about the rate limits the Lia API enforces and how to handle them effectively.

The Lia API uses rate limiting to ensure fair usage and protect against abuse. All API endpoints are subject to rate limits applied per API key.

Rate Limits

Default Limit: 120 requests per 60 seconds (2 requests/second) per API key

Rate limits are enforced using a sliding window algorithm, which provides a smooth rate limiting experience without sudden resets at fixed intervals.

Rate Limit Headers

Every API response includes rate limit information in the HTTP headers, allowing you to track your usage and avoid hitting limits:

Header	Description
X-RateLimit-Limit	The maximum number of requests you're permitted to make in the current rate limit window
X-RateLimit-Remaining	The number of requests remaining in the current rate limit window
X-RateLimit-Reset	The time at which the current rate limit window resets in UTC epoch seconds

Example Response:

HTTP/2 200 OK
Content-Type: application/json
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1706486460

{
  "user": {
    "id": "usr_123",
    "email": "[email protected]",
    "name": "John Doe"
  }
}

Rate Limit Exceeded Response

If you exceed the rate limit, the API returns a 429 Too Many Requests error with rate limit headers:

HTTP/2 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706486460
Retry-After: 60

{
  "code": "TOO_MANY_REQUESTS",
  "message": "Rate limit exceeded. Please try again later.",
  "status": 429
}

Response Headers:

• X-RateLimit-Limit: Your rate limit (e.g., 120)

• X-RateLimit-Remaining: Always 0 when rate limited

• X-RateLimit-Reset: Unix timestamp when you can make requests again

• Retry-After: Number of seconds to wait before retrying