[Dashboard] Improve error handling in billing checkout process (#7318)

# Add "Go back" button to Stripe redirect error page and improve error handling

This PR enhances the Stripe redirect error page by adding a "Go back" button, allowing users to navigate away from error states. It also improves error handling in the billing checkout flow by:

1. Converting `getBillingCheckoutUrl()` to return structured responses with proper error messages
2. Adding specific error messages for different HTTP status codes (402 for outstanding invoices, 429 for rate limiting)
3. Displaying these more descriptive error messages to users when checkout fails

These changes provide a better user experience when errors occur during the checkout process.

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

## Summary by CodeRabbit

- **New Features**
  - Added a "Go back" button to the Stripe redirect error page, allowing users to easily return to the previous screen.

- **Bug Fixes**
  - Improved error handling during the checkout process, providing clearer error messages for issues such as authentication, outstanding invoices, rate limiting, and unknown errors. Error messages are now displayed directly on the error page when checkout fails.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: jnsdls

apps/dashboard/src/app/(app)/(stripe)/_components/StripeRedirectErrorPage.tsx

@@ -1,15 +1,29 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import { useDashboardRouter } from "@/lib/DashboardRouter";
 import { AlertTriangleIcon } from "lucide-react";
 
 export function StripeRedirectErrorPage(props: {
   errorMessage: string;
 }) {
+  const router = useDashboardRouter();
+
   return (
     <div className="flex min-h-dvh items-center justify-center">
       <div className="flex flex-col items-center text-center text-sm">
         <div className="mb-4 rounded-full border p-2">
           <AlertTriangleIcon className="size-5 text-destructive-text" />
         </div>
         <p className="font-medium text-base">{props.errorMessage}</p>
+
+        <Button
+          variant="outline"
+          className="mt-4"
+          onClick={() => router.back()}
+        >
+          Go back
+        </Button>
       </div>
     </div>
   );

apps/dashboard/src/app/(app)/(stripe)/checkout/[team_slug]/[sku]/page.tsx

@@ -58,18 +58,16 @@ export default async function CheckoutPage(props: {
       break;
     }
     default: {
-      const billingUrl = await getBillingCheckoutUrl({
+      const response = await getBillingCheckoutUrl({
         teamSlug: params.team_slug,
         sku: decodeURIComponent(params.sku) as Exclude<ProductSKU, null>,
       });
 
-      if (!billingUrl) {
-        return (
-          <StripeRedirectErrorPage errorMessage="Failed to load checkout page" />
-        );
+      if (response.status === "error") {
+        return <StripeRedirectErrorPage errorMessage={response.error} />;
       }
 
-      redirect(billingUrl);
+      redirect(response.data);
       break;
     }
   }

apps/dashboard/src/app/(app)/(stripe)/utils/billing.ts

@@ -7,11 +7,14 @@ import { getAuthToken } from "../../api/lib/getAuthToken";
 export async function getBillingCheckoutUrl(options: {
   teamSlug: string;
   sku: Exclude<ProductSKU, null>;
-}): Promise<string | undefined> {
+}) {
   const token = await getAuthToken();
 
   if (!token) {
-    return undefined;
+    return {
+      status: "error",
+      error: "You are not logged in",
+    } as const;
   }
 
   const res = await fetch(
@@ -29,16 +32,43 @@ export async function getBillingCheckoutUrl(options: {
     },
   );
   if (!res.ok) {
-    console.error("Failed to create checkout link", await res.json());
-    return undefined;
+    const text = await res.text();
+    console.error("Failed to create checkout link", text, res.status);
+    switch (res.status) {
+      case 402: {
+        return {
+          status: "error",
+          error:
+            "You have outstanding invoices, please pay these first before re-subscribing.",
+        } as const;
+      }
+      case 429: {
+        return {
+          status: "error",
+          error: "Too many requests, please try again later.",
+        } as const;
+      }
+      default: {
+        return {
+          status: "error",
+          error: "An unknown error occurred, please try again later.",
+        } as const;
+      }
+    }
   }
 
   const json = await res.json();
   if (!json.result) {
-    return undefined;
+    return {
+      status: "error",
+      error: "An unknown error occurred, please try again later.",
+    } as const;
   }
 
-  return json.result as string;
+  return {
+    status: "success",
+    data: json.result as string,
+  } as const;
 }
 
 export async function getPlanCancelUrl(options: {