Manejo de Errores

Patrones para manejar timeouts del bridge, errores tipados de la API, estados de error en la UI, fallos de facturación y errores en el procesamiento de webhooks.

El manejo robusto de errores evita que un solo fallo arruine toda la experiencia del comerciante.

1. Maneja los timeouts del bridge con elegancia

Todas las acciones del bridge tienen un timeout de 5 segundos. Un timeout no significa necesariamente que la acción falló — significa que la respuesta no se recibió a tiempo.

const result = await bridge.toast.show("Saved!");
if (!result.success) {
  // Log for debugging but do not crash the UI
  console.warn("Toast action timed out:", result.error);
}

2. Maneja los errores de la API por tipo

El SDK exporta clases de error tipadas para que puedas responder apropiadamente a cada modo de fallo:

import { NotFoundError, RateLimitError, ValidationError } from "@whatalo/plugin-sdk";

try {
  await client.products.update(id, data);
} catch (error) {
  if (error instanceof NotFoundError) {
    showMessage("Product not found");
  } else if (error instanceof RateLimitError) {
    showMessage(`Too many requests. Try again in ${error.retryAfter}s`);
  } else if (error instanceof ValidationError) {
    showFieldErrors(error.fieldErrors);
  } else {
    // Unexpected error — surface a generic message
    showMessage("An unexpected error occurred");
  }
}

3. Muestra estados de error amigables para el usuario

Usa el componente Banner para mostrar errores en línea en vez de romper la página:

import { Banner } from "./components/whatalo-ui";

{error && (
  <Banner status="error" title="Error">
    {error.message}
  </Banner>
)}

4. Siempre verifica isReady antes de renderizar

El handshake del bridge es asíncrono. Renderizar tu UI principal antes de que isReady sea true significa que el contexto del bridge aún no está disponible.

import { Spinner } from "./components/whatalo-ui";
import { useAppBridge } from "@whatalo/plugin-sdk/bridge";

function App() {
  const { isReady } = useAppBridge();

  // Show spinner until the bridge is initialized
  if (!isReady) return <Spinner />;

  return <DashboardPage />;
}

5. Maneja los errores de facturación

Los métodos de facturación lanzan errores al fallar. Envuélvelos en try/catch e informa al comerciante:

try {
  await bridge.billing.requestSubscription("pro");
} catch (error) {
  bridge.toast.show("Could not start subscription. Please try again.", {
    variant: "error",
  });
}

6. Registra errores en los handlers de webhook

Siempre registra los fallos en tus handlers de webhook para poder diagnosticar problemas de entrega:

export async function POST(request: Request) {
  try {
    const payload = await request.json();
    await processOrder(payload);
    return new Response("OK", { status: 200 });
  } catch (error) {
    console.error("[webhook] order.created failed:", error);
    return new Response("Processing failed", { status: 500 });
  }
}

Usa whatalo logs para revisar el historial de entrega de webhooks y reintentar eventos fallidos:

# Follow failed webhook deliveries in real time
whatalo logs --status failed --follow