@meeting-baas/sdk - v2 API Reference / v2-error-handling

Error Handling in v2 API

The v2 API provides detailed, structured error responses that make it easy to handle errors gracefully.

Error Response Structure

interface ErrorResponse {
  success: false;
  error: string;        // Human-readable error message
  code: string;         // Machine-readable error code
  statusCode: number;   // HTTP status code
  details: unknown | null; // Additional error details
}

Common Error Codes

Authentication Errors

Code	Status	Description
`INVALID_API_KEY`	401	API key is invalid or missing
`UNAUTHORIZED`	401	Insufficient permissions

const result = await client.createBot({ ... });

if (!result.success && result.code === "INVALID_API_KEY") {
  console.error("Please check your API key");
}

Validation Errors

Code	Status	Description
`INVALID_MEETING_URL`	400	Meeting URL format is invalid
`VALIDATION_ERROR`	400	Request parameters failed validation

const result = await client.createBot({
  meeting_url: "invalid-url",
  bot_name: "Test Bot"
});

if (!result.success && result.code === "INVALID_MEETING_URL") {
  console.error("Invalid meeting URL:", result.error);
  console.log("Details:", result.details);
}

Rate Limiting

Code	Status	Description
`RATE_LIMIT_EXCEEDED`	429	Too many requests

const result = await client.createBot({ ... });

if (!result.success && result.code === "RATE_LIMIT_EXCEEDED") {
  const retryAfter = result.details?.retryAfter || 60;
  console.log(`Rate limited. Retry after ${retryAfter} seconds`);
}

Resource Errors

Code	Status	Description
`BOT_NOT_FOUND`	404	Bot with specified ID not found
`CALENDAR_NOT_FOUND`	404	Calendar not found
`BOT_ALREADY_IN_MEETING`	409	Bot is already in this meeting

Error Handling Patterns

Type-Safe Error Handling

async function createBotSafely(meetingUrl: string, botName: string) {
  const result = await client.createBot({
    meeting_url: meetingUrl,
    bot_name: botName
  });

  if (result.success) {
    return { ok: true, botId: result.data.bot_id };
  }

  // Handle specific errors
  switch (result.code) {
    case "INVALID_MEETING_URL":
      return { ok: false, reason: "invalid_url" };

    case "RATE_LIMIT_EXCEEDED":
      return { ok: false, reason: "rate_limited" };

    case "UNAUTHORIZED":
      return { ok: false, reason: "auth_error" };

    default:
      console.error("Unexpected error:", result.error);
      return { ok: false, reason: "unknown" };
  }
}

Retry Logic

async function createBotWithRetry(
  meetingUrl: string,
  botName: string,
  maxRetries = 3
) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    const result = await client.createBot({
      meeting_url: meetingUrl,
      bot_name: botName
    });

    if (result.success) {
      return result;
    }

    // Retry on rate limiting
    if (result.code === "RATE_LIMIT_EXCEEDED" && attempt < maxRetries) {
      const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
      console.log(`Rate limited. Retrying in ${delay}ms...`);
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    // Don't retry on other errors
    return result;
  }
}

Batch Operation Errors

Batch operations return partial success information:

const result = await client.batchCreateBots({
  bots: [
    { meeting_url: "https://meet.google.com/abc", bot_name: "Bot 1" },
    { meeting_url: "invalid-url", bot_name: "Bot 2" },
    { meeting_url: "https://zoom.us/j/123", bot_name: "Bot 3" }
  ]
});

if (result.success) {
  console.log(`Created ${result.data.length} bots`);

  // Check for partial failures
  if (result.errors && result.errors.length > 0) {
    console.log(`Failed to create ${result.errors.length} bots:`);
    result.errors.forEach((error, index) => {
      console.log(`  Bot ${index}: ${error.error} (${error.code})`);
    });
  }
}

Best Practices

Always check success first: Use type narrowing to access the correct response properties
Handle specific error codes: Don't rely solely on HTTP status codes
Log error details: The details field may contain valuable debugging information
Implement retry logic: For transient errors like rate limiting
Display user-friendly messages: Translate error codes to user-friendly messages

function getErrorMessage(code: string): string {
  const messages: Record<string, string> = {
    INVALID_MEETING_URL: "Please provide a valid meeting URL",
    RATE_LIMIT_EXCEEDED: "Too many requests. Please try again later",
    BOT_NOT_FOUND: "The requested bot could not be found",
    UNAUTHORIZED: "You don't have permission to perform this action"
  };

  return messages[code] || "An unexpected error occurred";
}

Error Handling in v2 API

On this page