# API Rate Limiting Strategy

We need to implement rate limiting before the v2 launch. Current system has no throttling and we've seen abuse patterns from scrapers.

## Proposed Approach

### Token Bucket Algorithm

Each API key gets a bucket of 100 tokens, refilled at 10/sec. Burst-friendly but prevents sustained abuse.

```
Rate-Limit: 100 requests/10s
Retry-After: <seconds>
X-RateLimit-Remaining: <count>
```

### Tiers

| Tier | Rate | Burst | Use case |
|------|------|-------|----------|
| Free | 60/min | 10 | Hobby projects |
| Pro | 600/min | 50 | Production apps |
| Enterprise | 6000/min | 200 | High-scale |

## Open Questions

1. Should we rate limit by IP or by API key?
2. Do we need separate limits for read vs write operations?
3. How do we handle WebSocket connections?

## Next Steps

- [ ] Benchmark Redis vs in-memory sliding window
- [ ] Draft error response format
- [ ] Update SDK clients with retry logic