Informed error parsing from api

Author: miguelg719

.changeset/kind-snails-judge.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+Informed error parsing from api

packages/core/lib/v3/api.ts

@@ -415,7 +415,9 @@ export class StagehandAPIClient {
 
           if (eventData.type === "system") {
             if (eventData.data.status === "error") {
-              throw new StagehandServerError(eventData.data.error);
+              const { error: errorMsg } = eventData.data;
+              // Throw plain Error to match local SDK behavior (useApi: false)
+              throw new Error(errorMsg);
             }
             if (eventData.data.status === "finished") {
               return eventData.data.result as T;
@@ -424,8 +426,9 @@ export class StagehandAPIClient {
             this.logger(eventData.data.message);
           }
         } catch (e) {
-          // Don't catch and re-throw StagehandServerError
-          if (e instanceof StagehandServerError) {
+          // Let Error instances pass through (server errors thrown above)
+          // Only wrap SyntaxError from JSON.parse as parse errors
+          if (e instanceof Error && !(e instanceof SyntaxError)) {
             throw e;
           }
 

packages/core/lib/v3/types/public/apiErrors.ts

@@ -34,3 +34,45 @@ export class StagehandResponseParseError extends StagehandAPIError {
     super(message);
   }
 }
+
+/**
+ * Enhanced error class for Stagehand operation failures.
+ * Includes error code and operation name for better debugging.
+ */
+export class StagehandOperationError extends StagehandAPIError {
+  public readonly code?: string;
+  public readonly operation?: string;
+
+  constructor(data: { error: string; code?: string; operation?: string }) {
+    super(data.error);
+    this.code = data.code;
+    this.operation = data.operation;
+  }
+
+  /**
+   * Returns true if the error is a user error (bad input, invalid arguments).
+   * User errors can typically be fixed by changing the request.
+   */
+  isUserError(): boolean {
+    return [
+      "INVALID_ARGUMENT",
+      "MISSING_ARGUMENT",
+      "INVALID_MODEL",
+      "INVALID_SCHEMA",
+      "EXPERIMENTAL_NOT_CONFIGURED",
+    ].includes(this.code ?? "");
+  }
+
+  /**
+   * Returns true if the operation might succeed on retry.
+   * These are transient failures that may resolve themselves.
+   */
+  isRetryable(): boolean {
+    return [
+      "ACTION_FAILED",
+      "TIMEOUT",
+      "LLM_ERROR",
+      "ELEMENT_NOT_FOUND",
+    ].includes(this.code ?? "");
+  }
+}

packages/core/lib/v3/v3.ts

@@ -530,34 +530,29 @@ export class V3 {
       await Promise.all(instances.map((i) => i._immediateShutdown(reason)));
     };
 
-    process.once("SIGINT", () => {
+    const handleSignal = async (signal: string) => {
       v3Logger({
         category: "v3",
-        message: "SIGINT: initiating shutdown",
-        level: 0,
-      });
-      for (const instance of V3._instances) {
-        if (instance.apiClient) {
-          void instance.apiClient.end();
-          return;
-        }
-      }
-      void shutdownAllImmediate("signal SIGINT");
-    });
-    process.once("SIGTERM", () => {
-      v3Logger({
-        category: "v3",
-        message: "SIGTERM: initiating shutdown",
+        message: `${signal}: initiating shutdown`,
         level: 0,
       });
+
+      // In API mode, let the server handle cleanup - don't close locally
       for (const instance of V3._instances) {
         if (instance.apiClient) {
-          void instance.apiClient.end();
+          const timeout = new Promise((r) => setTimeout(r, 5000));
+          await Promise.race([
+            instance.apiClient.end().catch(() => {}),
+            timeout,
+          ]);
           return;
         }
       }
-      void shutdownAllImmediate("signal SIGTERM");
-    });
+      await shutdownAllImmediate(`signal ${signal}`);
+    };
+
+    process.once("SIGINT", () => void handleSignal("SIGINT"));
+    process.once("SIGTERM", () => void handleSignal("SIGTERM"));
     process.once("uncaughtException", (err: unknown) => {
       v3Logger({
         category: "v3",

packages/core/tests/api-error-handling.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { StagehandResponseParseError } from "../lib/v3/types/public/apiErrors";
+
+describe("API Error Handling", () => {
+  describe("SSE error parsing", () => {
+    it("throws plain Error with raw message for server errors", () => {
+      // Simulate what happens in api.ts when SSE error is received
+      const serverErrorMessage =
+        "API key not valid. Please pass a valid API key.";
+      const eventData = {
+        type: "system",
+        data: {
+          status: "error",
+          error: serverErrorMessage,
+        },
+      };
+
+      // This simulates the error handling logic in api.ts execute()
+      if (eventData.data.status === "error") {
+        const { error: errorMsg } = eventData.data;
+        const thrownError = new Error(errorMsg);
+
+        // Verify it's a plain Error, not a wrapped type
+        expect(thrownError).toBeInstanceOf(Error);
+        expect(thrownError.constructor.name).toBe("Error");
+        expect(thrownError.message).toBe(serverErrorMessage);
+      }
+    });
+
+    it("wraps SyntaxError in StagehandResponseParseError for JSON parse failures", () => {
+      const invalidJson = "not valid json {";
+
+      try {
+        JSON.parse(invalidJson);
+      } catch (e) {
+        // This simulates the catch block logic in api.ts
+        if (e instanceof Error && !(e instanceof SyntaxError)) {
+          throw e; // Would pass through
+        }
+
+        // SyntaxError gets wrapped
+        const errorMessage = e instanceof Error ? e.message : String(e);
+        const wrappedError = new StagehandResponseParseError(
+          `Failed to parse server response: ${errorMessage}`,
+        );
+
+        expect(wrappedError).toBeInstanceOf(StagehandResponseParseError);
+        expect(wrappedError.message).toContain(
+          "Failed to parse server response",
+        );
+      }
+    });
+  });
+});

packages/core/tests/public-api/public-error-types.test.ts

@@ -37,6 +37,7 @@ export const publicErrorTypes = {
   StagehandInvalidArgumentError: Stagehand.StagehandInvalidArgumentError,
   StagehandMissingArgumentError: Stagehand.StagehandMissingArgumentError,
   StagehandNotInitializedError: Stagehand.StagehandNotInitializedError,
+  StagehandOperationError: Stagehand.StagehandOperationError,
   StagehandResponseBodyError: Stagehand.StagehandResponseBodyError,
   StagehandResponseParseError: Stagehand.StagehandResponseParseError,
   StagehandServerError: Stagehand.StagehandServerError,