browser-sdk: include API error details in non-retriable bulk logs

Author: roncohen

packages/browser-sdk/src/bulkQueue.ts

@@ -11,6 +11,7 @@ const WARN_AFTER_CONSECUTIVE_FAILURES = 10;
 const WARN_AFTER_FAILURE_MS = 5 * 60 * 1000;
 const WARN_THROTTLE_MS = 15 * 60 * 1000;
 const DROP_ERROR_THROTTLE_MS = 15 * 60 * 1000;
+const MAX_RESPONSE_BODY_PREVIEW_CHARS = 500;
 
 type PayloadContext = {
   active?: boolean;
@@ -66,6 +67,12 @@ export type BulkQueueOptions = {
   logger?: Logger;
 };
 
+type BulkErrorDetails = {
+  responseBody?: string;
+  apiErrorCode?: string;
+  apiErrorMessage?: string;
+};
+
 function getSessionStorage(): Storage | null {
   try {
     if (typeof sessionStorage === "undefined") {
@@ -248,17 +255,20 @@ export class BulkQueue {
       const res = await this.sendBulk(batch);
       if (!res.ok) {
         if (res.status >= 400 && res.status < 500) {
-          const responseBody = await this.getResponseBodyPreview(res);
+          const errorDetails = await this.getResponseErrorDetails(res);
+          const errorSummary = this.getApiErrorSummary(errorDetails);
           this.retryCount = 0;
           this.firstFailureAt = null;
           this.consecutiveFailures = 0;
           this.lastWarnAt = null;
           this.logger?.error(
-            "bulk request failed with non-retriable status; dropping batch",
+            errorSummary
+              ? `bulk request failed with non-retriable status; dropping batch: ${errorSummary}`
+              : "bulk request failed with non-retriable status; dropping batch",
             {
               status: res.status,
               statusText: res.statusText,
-              responseBody,
+              ...errorDetails,
             },
           );
           nextDelayMs = this.flushDelayMs;
@@ -397,15 +407,64 @@ export class BulkQueue {
     }
   }
 
-  private async getResponseBodyPreview(res: Response) {
+  private getApiErrorSummary(errorDetails: BulkErrorDetails) {
+    const code = errorDetails.apiErrorCode;
+    const message = errorDetails.apiErrorMessage;
+    if (code && message) {
+      return `${code}: ${message}`;
+    }
+    return message ?? code;
+  }
+
+  private async getResponseErrorDetails(res: Response): Promise<BulkErrorDetails> {
     try {
       const body = await res.text();
       if (!body) {
-        return undefined;
+        return {};
       }
-      return body.slice(0, 500);
+
+    let apiErrorCode: string | undefined;
+    let apiErrorMessage: string | undefined;
+    try {
+      const parsed: unknown = JSON.parse(body);
+      const parsedError = this.extractApiError(parsed);
+      apiErrorCode = parsedError.code;
+      apiErrorMessage = parsedError.message;
+    } catch {
+      // ignore JSON parse failures
+    }
+
+      return {
+        responseBody: body.slice(0, MAX_RESPONSE_BODY_PREVIEW_CHARS),
+        apiErrorCode,
+        apiErrorMessage,
+      };
     } catch {
-      return undefined;
+      return {};
     }
   }
+
+  private extractApiError(value: unknown): { code?: string; message?: string } {
+    if (!isObject(value)) {
+      return {};
+    }
+
+    const topLevelCode = typeof value.code === "string" ? value.code : undefined;
+    const topLevelMessage =
+      typeof value.message === "string" ? value.message : undefined;
+
+    const error = value.error;
+    if (!isObject(error)) {
+      return {
+        code: topLevelCode,
+        message: topLevelMessage,
+      };
+    }
+
+    return {
+      code: typeof error.code === "string" ? error.code : topLevelCode,
+      message:
+        typeof error.message === "string" ? error.message : topLevelMessage,
+    };
+  }
 }

packages/browser-sdk/test/bulkQueue.test.ts

@@ -122,6 +122,48 @@ describe("BulkQueue", () => {
     expect(sendBulk).toHaveBeenCalledTimes(1);
   });
 
+  it("includes parsed API error details for non-retriable 4xx responses", async () => {
+    const body = JSON.stringify({
+      success: false,
+      error: {
+        message:
+          'Invalid publishableKey "pub_prod_vxuMahSZOnhzvAfiOnZ9rj"',
+        code: "INVALID_API_KEY",
+      },
+    });
+    const sendBulk = vi
+      .fn<(events: BulkEvent[]) => Promise<Response>>()
+      .mockResolvedValue(
+        new Response(body, {
+          status: 401,
+          headers: { "content-type": "application/json" },
+        }),
+      );
+    const logger = {
+      debug: vi.fn(),
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    };
+    const queue = new BulkQueue(sendBulk, {
+      flushDelayMs: 10,
+      logger,
+    });
+
+    await queue.enqueue(trackEvent);
+    await vi.advanceTimersByTimeAsync(10);
+
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.stringContaining("INVALID_API_KEY"),
+      expect.objectContaining({
+        status: 401,
+        apiErrorCode: "INVALID_API_KEY",
+        apiErrorMessage:
+          'Invalid publishableKey "pub_prod_vxuMahSZOnhzvAfiOnZ9rj"',
+      }),
+    );
+  });
+
   it("does not drop newly queued events when an older batch completes", async () => {
     let resolveFirstSend: ((res: Response) => void) | undefined;
     const firstSend = new Promise<Response>((resolve) => {