FeaturesRate Limiting

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

EndpointLimitWindowPer
Login10 requests1 minuteIP address
Login (per-email)5 requests15 minutesEmail address
Register5 requests1 minuteIP address
OTP Send3 requests5 minutesEmail/phone
OTP Verify3 requests5 minutesIdentifier
Password Reset3 requests15 minutesEmail address
Email Verification Resend3 requests1 minuteEmail address

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

API Endpoints

AuthenticationLimitWindowPer
No API key100 requests1 minuteIP address
With API key1,000 requests1 minuteProject

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
HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix 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:

PlanWorkspace Tool CallsGateway Requests
Free1,000 / day100 / minute
Starter10,000 / day500 / minute
Pro100,000 / day2,000 / minute
BusinessUnlimited10,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.

ObservabilitySecurity