Handle errors

The SDK converts supported problem responses into BeaconError objects.

Catch a Beacon error

import { BeaconError } from "@beacon/sdk";

try {
  await beacon.channels.list();
} catch (error) {
  if (!(error instanceof BeaconError)) throw error;

  console.error({
    code: error.code,
    detail: error.detail,
    requestId: error.requestId,
    retryable: error.retryable,
    retryAfterSeconds: error.retryAfterSeconds,
    status: error.status,
  });
}

Show the recovery action

Use detail for a safe explanation. Use code to choose a known application action.

Use requestId in support messages. Never show raw credentials or provider responses.

If approvalUrl exists, send the signed-in user to that exact Beacon page.

For a rate limit, wait for retryAfterSeconds. Then follow the operation retry rule.