# Rate Limiting

> Aerostack rate limits by endpoint and auth method. Limits, headers, and backoff guidance for auth, API key, and anonymous requests.

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:

```json
{
  "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.