Error Handling

{
  "error": {
    "code": "validation_error",
    "message": "Request body is missing required field: email"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "Request body is invalid.",
    "fields": {
      "email": "Must be a valid email address",
      "metadata": "Must be a JSON object"
    }
  }
}

import {
  AliasKitError,
  AuthError,
  ApiError,
  EmailTimeoutError,
  SmsTimeoutError,
  BillingError,
  BillingErrorCode,
} from "aliaskit";

try {
  await ak.identities.create();
} catch (err) {
  if (err instanceof AliasKitError) {
    console.log(err.code);    // e.g. "auth_required"
    console.log(err.message); // human-readable description
  }
}

try {
  await ak.identities.list();
} catch (err) {
  if (err instanceof AuthError) {
    console.log(err.code); // "auth_required" | "auth_invalid" | "auth_forbidden"
  }
}

try {
  await ak.identities.get("nonexistent-id");
} catch (err) {
  if (err instanceof ApiError) {
    console.log(err.status);       // 404
    console.log(err.endpoint);     // "/v1/identities/nonexistent-id"
    console.log(err.responseBody); // raw JSON string
  }
}

try {
  const code = await ak.emails.waitForCode(identity.id, { timeout: 15_000 });
} catch (err) {
  if (err instanceof EmailTimeoutError) {
    console.log(err.timeoutMs); // 15000
  }
}

try {
  const code = await ak.sms.waitForCode(identity.id, { timeout: 15_000 });
} catch (err) {
  if (err instanceof SmsTimeoutError) {
    console.log(err.timeoutMs); // 15000
  }
}

try {
  await ak.identities.create({ phone: true });
} catch (err) {
  if (err instanceof BillingError) {
    console.log(err.code);         // "free_tier_phone_blocked"
    console.log(err.requiredPlan); // "pro"
  }
}

import { BillingErrorCode } from "aliaskit";

switch (err.code) {
  case BillingErrorCode.IDENTITY_LIMIT:
    // handle identity limit
    break;
  case BillingErrorCode.PHONE_BLOCKED:
    // handle phone blocked
    break;
  case BillingErrorCode.CARDS_BLOCKED:
    // handle cards blocked
    break;
}

async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err instanceof ApiError) {
        const retryable = err.status === 429 || err.status >= 500;
        if (retryable && attempt < maxRetries) {
          const delay = Math.min(1000 * 2 ** attempt, 10_000);
          const jitter = Math.random() * delay * 0.1;
          await new Promise((r) => setTimeout(r, delay + jitter));
          continue;
        }
      }
      throw err;
    }
  }
  throw new Error("Unreachable");
}

// Usage
const identity = await withRetry(() => ak.identities.create());

try {
  const identity = await ak.identities.create({ phone: true });
  const code = await ak.emails.waitForCode(identity.id, { timeout: 30_000 });
} catch (err) {
  if (err instanceof BillingError) {
    console.log(`Upgrade to ${err.requiredPlan} to use this feature.`);
  } else if (err instanceof EmailTimeoutError) {
    console.log("No email received. Check that the signup flow sends to the right address.");
  } else if (err instanceof AuthError) {
    console.log("API key is invalid. Regenerate it from the dashboard.");
  } else if (err instanceof ApiError && err.status === 404) {
    console.log("Identity not found. It may have been deleted.");
  } else {
    throw err;
  }
}

// Bad: manual polling (burns rate limit)
while (true) {
  const emails = await ak.emails.list(identity.id);
  if (emails.length > 0) break;
  await new Promise((r) => setTimeout(r, 1000));
}

// Good: uses realtime subscription internally
const email = await ak.emails.waitForCode(identity.id, {
  timeout: 30_000,
});

const subscription = ak.realtime.subscribe(identity.id, {
  events: ["email.received", "sms.received"],
  onEvent: (event) => {
    console.log(`Received ${event.type}:`, event.data);
  },
});

// Trigger the signup flow...

// Clean up when done
subscription.unsubscribe();