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