The { data, error } result

Instead of throwing exceptions on failed requests, every method in wapi-cloud returns a promise that resolves to a strongly-typed WhatsappResponse<T> object. Exactly one of data or error will be non-null:

interface WhatsappResponse<T> {
  data: T | null;
  error: WhatsappApiError | null;
  status: number;      // HTTP status code (0 for network/client errors)
  statusText: string;  // HTTP status text
  raw: unknown;        // Untouched raw JSON payload from Meta Graph API
}

Checking a result with TypeScript

Because data and error are mutually exclusive, checking error first lets TypeScript narrow data to its non-null type automatically:

const { data, error, status } = await whatsapp.templates.list();

if (error) {
  // data is narrowed to null
  console.error("[" + error.type + "] Code " + error.code + ": " + error.message);
  if (error.fbtraceId) console.error("Trace ID for Meta support:", error.fbtraceId);
  return;
}

// error is narrowed to null — data.items is 100% type-safe
console.log("Fetched " + data.items.length + " templates (HTTP " + status + ")");

The WhatsappApiError class

Every failure is normalized into a WhatsappApiError instance attached to response.error:

Automatic retries & backoff

wapi-cloud automatically retries failed requests that return HTTP 429 (rate limits) or 5xx (server errors) up to maxRetries times (default: 3). Retries use exponential backoff with full jitter and respect Retry-After headers.

Common WhatsApp error codes

wapi-cloud includes built-in descriptions for common Graph API error codes:

Why no try/catch?

In messaging applications, expected operational states — rate limits, unapproved templates, or customers outside the 24-hour window — are normal program outcomes, not fatal runtime crashes.

• Compile-time safety: You cannot accidentally forget to handle an error — TypeScript prevents accessing data properties without checking error first.
• Batch resilience: Using Promise.all() across hundreds of messages won't abort early if a single recipient is invalid.
• Clean async code: No nested try/catch boilerplate cluttering your business logic.