[Phase 1] Rate Limiting & Throttling Controls

[syed-reza98]

Priority: P0 (Critical)

Phase: 1 - E-Commerce Core
Estimate: 2 days
Type: Story

Context

Introduce per-organization and per-IP rate limiting to guard against abuse, preserve performance, and protect payment/idempotency layers.

Scope

• Basic in-memory dev limiter (sliding window or token bucket)
• Interface abstraction for future Redis store
• Limits (initial suggested):
  • Auth endpoints: 10/min/IP
  • Order create: 60/min/org
  • Payment attempt: 30/min/org
  • Webhook endpoint create: 20/hour/org
• Response: 429 with Retry-After header
• Metrics: rate.limit.hit.count, rate.limit.block.count

Acceptance Criteria

• Exceeding configured limit returns 429 with correct Retry-After
• Limits configurable via env for each category
• Rate limiting integrates with Idempotency (still single side effect) without double counting
• Structured log on block includes route, orgId, ip, limit key
• Minimal overhead (< 1ms avg per check dev)

Data Model (Future Redis)

Key pattern: rl:{scope}:{id} storing counters & timestamps

Dependencies

• Complements Idempotency ([Phase 1] Idempotency Key & Request Replay Safety Layer #66) and RBAC ([Phase 1] RBAC & Scoped API Tokens (Multi-Tenant Authorization) #67)
• Protects Webhooks management ([Phase 1] Webhook Infrastructure & Delivery Guarantees #69)

Metrics Targets

• Correct block detection for simulated abuse scenario (100 rapid requests) > 95% blocked

Testing Checklist

• Exceed auth endpoint limit
• Exceed order create limit concurrently
• Ensure legitimate spaced requests pass

Risk

Resource exhaustion & financial abuse if absent (score: 16). Critical protective layer.

References

• docs/GITHUB_ISSUES_COMPARISON_ANALYSIS.md (rate limiting gap)