Rate limits documented

Severity: Recommended

API consumers should be able to discover rate limits before hitting them - either via documentation or response headers.

Check automatically:

1. Check documentation for rate limit info:

# README mentions rate limits
grep -iE "rate.?limit|throttl|requests per" README.md 2>/dev/null

# API documentation
grep -rE "rate.?limit|throttl|requests per|quota" docs/ api-docs/ 2>/dev/null

# OpenAPI/Swagger spec
grep -rE "rate|limit|throttle|x-ratelimit" openapi.yaml swagger.json api.yaml 2>/dev/null

2. Check for rate limit response headers:

# X-RateLimit headers in code
grep -rE "X-RateLimit-Limit|X-RateLimit-Remaining|X-RateLimit-Reset" src/ lib/ app/ 2>/dev/null

# RateLimit headers (newer standard)
grep -rE "RateLimit-Limit|RateLimit-Remaining|RateLimit-Reset" src/ lib/ app/ 2>/dev/null

# Rate limiter header configuration
grep -rE "headers.*true|standardHeaders|legacyHeaders|draft.*headers" src/ lib/ app/ 2>/dev/null

3. Check API response examples:

# Example responses in docs that show rate limit headers
grep -rE "X-RateLimit|RateLimit-" docs/ examples/ 2>/dev/null

# Rate limit error examples
grep -rE "429|Too Many" docs/ examples/ 2>/dev/null

Ask user:

• "Where would an API consumer learn about rate limits?"
• "Do responses include rate limit headers?"
• "Are different endpoint limits documented separately?"

Cross-reference with:

• RATE-001 (actual limits configured)
• RATE-002 (429 response format)
• DOC-001 (API documentation)

Pass criteria:

• Rate limits documented in API docs, README, or OpenAPI spec
• OR rate limit headers included in responses (X-RateLimit-* or RateLimit-*)
• Consumers can discover limits before hitting them

Fail criteria:

• No documentation of rate limits
• No rate limit headers in responses
• Consumers only discover limits by getting 429'd

Evidence to capture:

• Where limits are documented (if anywhere)
• Rate limit headers present in responses
• Whether different endpoints have documented different limits

---