Rate limit errors explain when to retry

A 429 response with no Retry-After header and no client-side timing message forces users to guess when to try again, which produces two bad outcomes: they either give up, or they hammer retry and trigger a retry storm that extends the rate-limit window. RFC 6585 defines Retry-After precisely so clients and humans can coordinate backoff. Without it, the rate limiter is invisible to the user and indistinguishable from a 500, erasing the distinction between throttling and an outage.

Return Retry-After on every 429 response and surface the value on the client so users see a concrete wait time instead of a generic error. Match the header value to your limiter's window. Edit the rate-limit handler in middleware.ts or your API route:

return NextResponse.json(
  { error: 'Too many requests', retryAfter: 60 },
  { status: 429, headers: { 'Retry-After': '60' } }
)

On the client, branch on response.status === 429 and display Please wait ${retryAfter} seconds rather than the generic error component.