Error Handling

Every failure surfaced by the SDK is a or one of its subclasses. Branch on the subclass with instanceof for broad handling, or switch on error.code for precise recovery.

The error hierarchy

import {
  WhatsAppError,
  AuthenticationError,
  ConnectionError,
  NotFoundError,
  RateLimitError,
  ValidationError,
} from "@photon-ai/whatsapp-business";

try {
  await client.messages.send({ to: "+15551234567", text: "Hi" });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // bad access token, missing scopes
  } else if (error instanceof RateLimitError) {
    // backoff and retry
  } else if (error instanceof ValidationError) {
    // recipient format, content shape, template parameters
  } else if (error instanceof ConnectionError) {
    // transient network / server issue
  } else if (error instanceof NotFoundError) {
    // mediaId expired, messageId unknown
  } else if (error instanceof WhatsAppError) {
    // anything else surfaced by the SDK
  }
}

Subclass	Maps from gRPC
`AuthenticationError`	`UNAUTHENTICATED`, `PERMISSION_DENIED`
`NotFoundError`	`NOT_FOUND`
`RateLimitError`	`RESOURCE_EXHAUSTED`
`ValidationError`	`INVALID_ARGUMENT`, `FAILED_PRECONDITION`
`ConnectionError`	`UNAVAILABLE`, `DEADLINE_EXCEEDED`
`WhatsAppError`	Everything else

Error fields

Every WhatsAppError carries:

Field	Description
`code`	Canonical error code — one of `ErrorCode`.
`retryable`	`true` when the caller can safely retry with backoff.
`grpcCode`	Numeric gRPC status code (mirrors `nice-grpc-common`’s `Status` enum).
`context`	`Record<string, string>` of extra server-provided context.
`cause`	The underlying error, when one was thrown by the transport.

Error codes

ErrorCode

Canonical error codes returned by the server.

Code	Value
`unauthenticated`	`"unauthenticated"`
`unauthorized`	`"unauthorized"`
`rateLimitExceeded`	`"rateLimitExceeded"`
`notFound`	`"notFound"`
`invalidArgument`	`"invalidArgument"`
`preconditionFailed`	`"preconditionFailed"`
`serviceUnavailable`	`"serviceUnavailable"`
`timeout`	`"timeout"`
`internalError`	`"internalError"`
`networkError`	`"networkError"`

Switch on code when you want to react to a specific failure mode rather than a whole class:

try {
  await client.messages.send({ to, text: "Hi" });
} catch (error) {
  if (error instanceof WhatsAppError) {
    switch (error.code) {
      case "rateLimitExceeded":
        await sleep(exponentialBackoff());
        break;
      case "preconditionFailed":
        // 24-hour window expired — send a template instead
        break;
      case "unauthenticated":
        // rotate token
        break;
    }
  }
}

Retrying

The SDK can retry transient errors automatically. Opt in via ClientOptions.retry:

const client = createClient({
  accessToken: "...",
  phoneNumberId: "...",
  appSecret: "...",
  retry: true, // default settings
});

// Or tune the behaviour
const client2 = createClient({
  accessToken: "...",
  phoneNumberId: "...",
  appSecret: "...",
  retry: {
    maxAttempts: 5,
    initialDelay: 250,
    maxDelay: 10_000,
  },
});

Retries only fire when error.retryable === true. Non-retryable errors (validation failures, auth issues) propagate immediately — don’t wrap them in your own retry loop. Streaming errors in events.subscribe() trigger the reconnect machinery rather than throwing — see Events → Reconnection. Errors from unary calls (messages.send, media.upload, events.fetchMissed) throw.

Advanced Kits

Opensource Kits

Utilities

Error Handling

The error hierarchy

Error fields

Error codes

Retrying

​The error hierarchy

​Error fields

​Error codes

​Retrying

​Subscribe vs unary calls

The error hierarchy

Error fields

Error codes

Retrying

Subscribe vs unary calls