Rate Limiting

Aerostack applies rate limits to protect the platform and ensure fair usage. Limits vary by endpoint and authentication method.

Rate Limit Tiers

Authentication Endpoints

Endpoint	Limit	Window	Per
Login	10 requests	1 minute	IP address
Login (per-email)	5 requests	15 minutes	Email address
Register	5 requests	1 minute	IP address
OTP Send	3 requests	5 minutes	Email/phone
OTP Verify	3 requests	5 minutes	Identifier
Password Reset	3 requests	15 minutes	Email address
Email Verification Resend	3 requests	1 minute	Email address

Authentication rate limits use atomic counters (Durable Object-backed) to prevent brute-force attacks with guaranteed accuracy under high concurrency.

API Endpoints

Authentication	Limit	Window	Per
No API key	100 requests	1 minute	IP address
With API key	1,000 requests	1 minute	Project

API rate limits use KV-based counters which are slightly permissive under burst traffic (a few extra requests may pass through during concurrent spikes). This is by design — API limits are for fair usage, not security enforcement.

Response Headers

Every API response includes rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1711843200

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the window resets

Handling 429 Responses

When you exceed a rate limit, the API returns HTTP 429:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 45 seconds."
  }
}

Best practices:

1. Respect the X-RateLimit-Remaining header — slow down before hitting the limit
2. Use exponential backoff — wait 1s, 2s, 4s, 8s on repeated 429s
3. Check X-RateLimit-Reset — wait until the reset timestamp before retrying
4. Batch requests — use bulk endpoints where available instead of individual calls

Per-Plan Limits

Higher plans get increased limits for workspace and gateway endpoints:

Plan	Workspace Tool Calls	Gateway Requests
Free	1,000 / day	100 / minute
Starter	10,000 / day	500 / minute
Pro	100,000 / day	2,000 / minute
Business	Unlimited	10,000 / minute

Account Lockout

After repeated failed authentication attempts, accounts may be temporarily locked:

• 5 failed login attempts (per email, 15-minute window) → 15-minute lockout
• 3 failed OTP attempts (per identifier, 5-minute window) → 5-minute lockout

Lockouts apply to the specific credential, not the IP address. Other accounts from the same IP are unaffected.