Lithtrix enforces two kinds of limits: a per-minute request rate that prevents burst traffic, and a lifetime call cap on the Free tier. Understanding the difference matters because each limit surfaces differently in API responses — one returns an HTTP error, the other appears inside the normal response body.
Limits by tier
| Tier | Per-minute limit | Lifetime cap |
|---|
| Free | 60 requests/min | 300 calls |
| Pro | 600 requests/min | Unlimited |
What happens when you hit a limit
Per-minute rate limit
When you exceed the per-minute limit, the API returns HTTP 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.
{
"status": "error",
"error_code": "RATE_LIMIT_EXCEEDED",
"message": "Per-minute rate limit exceeded. See Retry-After header."
}
Retry-After value and back off for that duration before resending the request.
Lifetime cap (Free tier)
Reaching the 300-call lifetime cap does not produce an HTTP error. The search request succeeds and returns results, but the usage object in the response body will show "over_limit": true with error code OVER_LIMIT. This lets your agent detect the cap without special error handling and decide whether to prompt the user to upgrade.
The Free tier lifetime cap never resets. It is 300 calls total across the life of your API key — not 300 per month.
The usage object
Every search response includes a usage field:
{
"usage": {
"calls_total": 42,
"calls_remaining": 258,
"over_limit": false,
"upgrade_url": "/v1/billing/setup"
}
}
| Field | Description |
|---|
calls_total | Total calls made with this key |
calls_remaining | Calls remaining before the lifetime cap (Free tier only) |
over_limit | true when the lifetime cap is reached |
upgrade_url | Path to the billing setup endpoint |
Checking your usage
To check your current usage outside of a search response, call the billing endpoint:
curl https://lithtrix.ai/v1/billing \
-H "Authorization: Bearer ltx_your_key"
{
"tier": "free",
"calls_total": 42,
"call_limit": 300
}
Upgrading to Pro
To remove the lifetime cap and raise your per-minute limit to 600 requests, upgrade to Pro via the billing API. Visit /v1/billing/setup for full instructions, or follow the upgrade path in Billing.