What
Add standard rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After) to all API responses. The backend has a comprehensive rate limiting system (tiered, smart, organization-based) but clients currently have no way to know their rate limit status without hitting a 429.
Why
Without rate limit headers, frontend developers and API consumers can't implement proactive throttling. They only discover limits after being rejected with a 429, which causes UX disruptions. Standard headers let clients display "slow down" messaging and implement exponential backoff correctly.
Scope
In scope:
- Add a middleware that appends rate limit headers to every API response
- Headers:
X-RateLimit-Limit (total allowed), X-RateLimit-Remaining (remaining), X-RateLimit-Reset (UTC epoch when limit resets), Retry-After (seconds, only on 429 responses)
- Integrate with the existing
smartRateLimiter and organizationRateLimiter middleware
- Support per-route overrides (e.g., auth endpoints may have lower limits)
Out of scope:
Acceptance Criteria
Technical Context
- Rate limiters:
backend/src/middleware/smartRateLimiter.ts, organizationRateLimiter.ts
- Throttling:
backend/src/middleware/throttlingMiddleware.ts
- App middleware stack:
backend/src/app.ts
- Tenant rate limiting:
backend/src/services/tenantRateLimitService.ts
What
Add standard rate limit headers (
X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset,Retry-After) to all API responses. The backend has a comprehensive rate limiting system (tiered, smart, organization-based) but clients currently have no way to know their rate limit status without hitting a 429.Why
Without rate limit headers, frontend developers and API consumers can't implement proactive throttling. They only discover limits after being rejected with a 429, which causes UX disruptions. Standard headers let clients display "slow down" messaging and implement exponential backoff correctly.
Scope
In scope:
X-RateLimit-Limit(total allowed),X-RateLimit-Remaining(remaining),X-RateLimit-Reset(UTC epoch when limit resets),Retry-After(seconds, only on 429 responses)smartRateLimiterandorganizationRateLimitermiddlewareOut of scope:
Acceptance Criteria
X-RateLimit-LimitandX-RateLimit-RemainingheadersX-RateLimit-Resetis included as a UTC epoch timestampRetry-Afterheader with seconds until resetTechnical Context
backend/src/middleware/smartRateLimiter.ts,organizationRateLimiter.tsbackend/src/middleware/throttlingMiddleware.tsbackend/src/app.tsbackend/src/services/tenantRateLimitService.ts