Rate Limiting

The API enforces rate limits to prevent abuse and ensure fair usage. Limits are applied per client IP address by default, or per authenticated user ID for certain endpoints.

Rate Limit Tiers

How Tiers Work

• General API (100/min): The default tier applied to most endpoints using the withRateLimit middleware or commonRateLimits.standard preset.
• AI Chat (20/min guest, 50/min user): AI endpoints use a stricter limit for unauthenticated users. When useUserId is enabled, authenticated users are tracked by their user ID instead of IP, giving them a higher allowance.
• Auth Login (5/15min): Protects against brute-force password attacks. Applies per IP address.
• Password Reset (3/hr): Prevents abuse of password reset emails. Applies per IP address.

Response Headers

Every rate-limited response includes these headers:

These headers are included on both successful and rejected responses, so clients can proactively track their usage.

Rate Limit Exceeded Response

When a client exceeds the rate limit, the API returns:

{
  "error": "Rate limit exceeded",
  "retryAfter": 42
}

The response also includes the standard rate limit headers with X-RateLimit-Remaining: 0.

Client Identification

The rate limiter identifies clients using the following priority:

For endpoints configured with useUserId: true, authenticated users are tracked by user-{userId} instead of their IP address, giving each user an independent rate limit.

Mobile App Bypass

Applying Rate Limits

Rate limits are applied to API route handlers using the withRateLimit middleware wrapper.

Direct Usage

import { withRateLimit } from '@/lib/middleware/api-helpers'

export const POST = withRateLimit(async (request) => {
  return NextResponse.json({ success: true })
}, {
  maxRequests: 10,
  windowSeconds: 60,
  useUserId: false,
})

Using Presets

import { commonRateLimits } from '@/lib/middleware/api-helpers'

export const POST = commonRateLimits.auth(async (request) => {
  // This handler is limited to 5 requests per 15 minutes per IP
  return NextResponse.json({ success: true })
})

Composing with Authentication

Rate limiting can be combined with authentication using the compose helper:

import { compose, withAuth, withRateLimit } from '@/lib/middleware/api-helpers'
import { RATE_LIMITS } from '@/lib/rate-limiter'
import { UserRole } from '@prisma/client'

export const POST = compose(
  (h) => withAuth(h, { roles: [UserRole.ADMIN] }),
  (h) => withRateLimit(h, RATE_LIMITS.API_GENERAL)
)(async (request) => {
  return NextResponse.json({ success: true })
})

Middleware is applied right to left: the request hits rate limiting first, then authentication.

Best Practices