app/stories/developer/DEV-006-rate-limiting.md

Understand API Rate Limits

ID: DEV-006 Priority: Low Status: Planned

User Story

As a developer, I want to understand and monitor API rate limits so that I can build applications that respect limits and handle throttling gracefully.

Acceptance Criteria

• Clear documentation of rate limits per endpoint
• Rate limit headers in API responses (X-RateLimit-*)
• Different limits for different API token tiers
• Dashboard showing current usage vs limits
• Alerts when approaching rate limits
• Retry-After header when rate limited
• Ability to request limit increase

Technical Notes

• Implement rate limiting middleware (consider express-rate-limit)
• Store rate limit counters in Redis for distributed systems
• Different limits: login attempts, API calls, token operations
• Consider sliding window algorithm for smooth limits
• 429 Too Many Requests response with helpful error message

Related TODOs

• New feature - API management