Rate limit errors show a specific, actionable message

Rate limit errors are one of the most common failure modes in AI chat products — per-user quotas, per-IP throttles, and upstream provider 429s all route through the same code path. Showing users a generic "Something went wrong" message for a 429 makes the product look broken when in fact the user has simply hit a quota and the correct action is to wait or upgrade. This is a direct conversion lever: rate-limited users on a paid tier should see an upgrade prompt, not an error toast.

In your API route at app/api/chat/route.ts, return structured 429 responses with a retry-after hint, and in src/components/chat/ChatWindow.tsx branch on response.status === 429 with a specific user-facing message. For subscription-gated limits, surface an upgrade CTA.

if (response.status === 429) {
  const { retryAfter } = await response.json();
  setError(`Rate limit reached. Try again in ${retryAfter} seconds.`);
}