feat(tasks): enhance FetchUrlJobError to include detailed HTTP error messages

- Added `httpErrorMessage` field to `FetchUrlJobErrorDetails` and `FetchUrlJobErrorInstance` for better error reporting.
- Updated `createFetchUrlHttpError` to construct messages that include JSON error details from the response body.
- Introduced `jsonMessageFromHttpBody` function to extract meaningful error messages from JSON responses.
- Modified `buildHttpError` to read and pass the error body to the error creation function.
- Added a test case to verify that JSON error messages are correctly surfaced in the `FetchUrlTask` error handling.

Author: sroussey

packages/tasks/src/task/FetchUrlJobError.ts

@@ -78,13 +78,15 @@ export interface FetchUrlJobErrorDetails {
   readonly url?: string;
   readonly httpStatus?: number;
   readonly httpStatusText?: string;
+  readonly httpErrorMessage?: string;
 }
 
 export type FetchUrlJobErrorInstance = JobError & {
   code: FetchUrlErrorCodeValue;
   url?: string;
   httpStatus?: number;
   httpStatusText?: string;
+  httpErrorMessage?: string;
   retryDate?: Date;
 };
 
@@ -104,6 +106,9 @@ function attachFetchUrlFields(
   if (details?.httpStatusText !== undefined) {
     withCode.httpStatusText = details.httpStatusText;
   }
+  if (details?.httpErrorMessage !== undefined) {
+    withCode.httpErrorMessage = details.httpErrorMessage;
+  }
   return withCode;
 }
 
@@ -177,18 +182,40 @@ export function createFetchUrlHttpError(
   url: string,
   status: number,
   statusText: string,
-  retryDate?: Date
+  retryDate?: Date,
+  body?: string
 ): FetchUrlJobErrorInstance {
   const code = httpStatusToFetchUrlErrorCode(status);
-  const message = `Failed to fetch ${url}: ${status} ${statusText}`;
+  const httpErrorMessage = jsonMessageFromHttpBody(body);
+  const statusPart = `${status} ${statusText}`;
+  const message =
+    httpErrorMessage !== undefined
+      ? `Failed to fetch ${url}: ${statusPart}: ${httpErrorMessage}`
+      : `Failed to fetch ${url}: ${statusPart}`;
   return createFetchUrlJobError(code, message, {
     url,
     httpStatus: status,
     httpStatusText: statusText,
+    httpErrorMessage,
     retryDate,
   });
 }
 
+/** Reads `{message}` from a JSON error body, if that field is a non-empty string. */
+export function jsonMessageFromHttpBody(body: string | undefined): string | undefined {
+  if (body === undefined || body.trim() === "") return undefined;
+  try {
+    const parsed: unknown = JSON.parse(body);
+    if (parsed === null || typeof parsed !== "object") return undefined;
+    const message = (parsed as { message?: unknown }).message;
+    if (typeof message !== "string") return undefined;
+    const trimmed = message.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * True when `error` (or a nested `cause`) is a dropped connection / DNS /
  * timeout rather than a completed body we failed to decode. `response.text()`

packages/tasks/src/task/FetchUrlTask.ts

@@ -411,7 +411,7 @@ function assertResponseType(
   );
 }
 
-function buildHttpError(url: string, response: Response): Error {
+async function buildHttpError(url: string, response: Response): Promise<Error> {
   let retryDate: Date | undefined;
   if (response.status === 429 || response.status === 503 || response.headers.get("Retry-After")) {
     const retryAfterStr = response.headers.get("Retry-After");
@@ -425,7 +425,22 @@ function buildHttpError(url: string, response: Response): Error {
       }
     }
   }
-  return createFetchUrlHttpError(url, response.status, response.statusText, retryDate);
+  const body = await readHttpErrorBody(response);
+  return createFetchUrlHttpError(url, response.status, response.statusText, retryDate, body);
+}
+
+const HTTP_ERROR_BODY_MAX_BYTES = 4096;
+
+async function readHttpErrorBody(response: Response): Promise<string | undefined> {
+  try {
+    const text = await response.text();
+    if (text.length === 0) return undefined;
+    return text.length > HTTP_ERROR_BODY_MAX_BYTES
+      ? text.slice(0, HTTP_ERROR_BODY_MAX_BYTES)
+      : text;
+  } catch {
+    return undefined;
+  }
 }
 
 /**
@@ -593,8 +608,9 @@ export class FetchUrlJob<
     }
 
     if (!response.ok) {
+      const error = await buildHttpError(input.url!, response);
       await discardBody(response);
-      throw buildHttpError(input.url!, response);
+      throw error;
     }
 
     if ((input.method ?? "GET").toUpperCase() === "HEAD") {

packages/test/src/test/task/FetchTask.test.ts

@@ -231,6 +231,36 @@ describe("FetchUrlTask", () => {
     expect(mockFetch.mock.calls.length).toBe(1);
   });
 
+  test("surfaces JSON message from a non-2xx body", async () => {
+    mockFetch.mockImplementation(() =>
+      Promise.resolve(
+        new Response(
+          JSON.stringify({
+            error: "Internal server error",
+            message: "upstream rejected the request",
+          }),
+          {
+            status: 500,
+            statusText: "Internal Server Error",
+            headers: { "Content-Type": "application/json" },
+          }
+        )
+      )
+    );
+
+    const error = await fetchUrl({
+      url: "https://api.example.com/items",
+      response_type: "json",
+    }).catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(JobTaskFailedError);
+    const jobFailed = error as JobTaskFailedError;
+    expect(jobFailed.jobError.message).toContain("upstream rejected the request");
+    expect(isFetchUrlJobError(jobFailed.jobError)).toBe(true);
+    if (isFetchUrlJobError(jobFailed.jobError)) {
+      expect(jobFailed.jobError.httpErrorMessage).toBe("upstream rejected the request");
+    }
+  });
+
   test("handles network errors", async () => {
     mockFetch.mockImplementation(() => Promise.reject(new Error("Network error")));