Skip to main content

​
Rate Limit Tiers

Rate limits are enforced per API key using a 60-second sliding window. Each key has a tier that determines its limits:
TierRequests/min (RPM)Tokens/min (TPM)
Free (default)60100,000
Starter300500,000
Pro1,0002,000,000
Enterprise5,00010,000,000
All new API keys start on the Free tier.

​
Per-Mode Limits

Expensive modes have lower RPM caps, scaled proportionally to your tier’s base RPM:
ModeFree RPMStarter RPMPro RPMEnterprise RPM
Text / Code / Auto603001,0005,000
Stealth301505002,500
Image201003331,666
Research15752501,250
Video1050166833
Dashboard sessions have a fixed 120 RPM limit.

​
How to Increase Your Limits

​
Check your current limits

curl https://hitheo.ai/api/v1/rate-limits \
  -H "Authorization: Bearer theo_sk_..."

​
Request a tier upgrade

curl -X POST https://hitheo.ai/api/v1/rate-limits/request-increase \
  -H "Authorization: Bearer theo_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "requested_tier": "starter",
    "use_case": "Production chatbot serving 10K daily active users",
    "expected_volume": "~200 RPM peak, 50K requests/day"
  }'
Requests are reviewed by the Theo platform team. You’ll receive a rate_limit.upgraded webhook when approved.

​
Credit Balance

In addition to request rate limits, each account has a credit balance. When your balance reaches zero, subsequent requests return 402 insufficient_credits until you top up.

​
Handling 429 Responses

When rate limited, the API returns:
  • Status 429 with one of three codes:
    • rate_limit_exceeded — universal RPM exceeded
    • mode_rate_limit_exceeded — per-mode RPM exceeded
    • token_limit_exceeded — TPM exceeded
  • Retry-After header — seconds to wait before retrying
The SDK handles this automatically with exponential backoff (configurable via maxRetries).

​
Response Headers

Every response includes rate limit headers reflecting your tier’s actual limits: 
X-Ratelimit-Limit-Requests: 60
X-Ratelimit-Remaining-Requests: 47
X-Ratelimit-Reset-Requests: 58s
X-Ratelimit-Limit-Tokens: 100000
X-Ratelimit-Remaining-Tokens: 85000
X-Ratelimit-Reset-Tokens: 42s