fix(ai): show provider error bodies when no message is recognized (#51978)

packages/ai/src/route/executor.ts

@@ -93,12 +93,18 @@ const decodeProviderBody = Schema.decodeUnknownOption(
   ),
 )
 
+const MAX_BODY_CHARS = 2000
+
+// Without a recognized message, show the raw body so the provider's explanation is never dropped.
 const providerMessage = (status: number, body: string | void) => {
-  const decoded = body === undefined ? undefined : Option.getOrUndefined(decodeProviderBody(body))
-  return (
-    [decoded?.error?.message, decoded?.message].find((message) => message?.trim()) ??
-    `Provider request failed with HTTP ${status}`
-  )
+  const fallback = `Provider request failed with HTTP ${status}`
+  const text = body?.trim() ?? ""
+  const decoded = Option.getOrUndefined(decodeProviderBody(text))
+  const message = [decoded?.error?.message, decoded?.message].find((message) => message?.trim())
+  if (message) return message
+  // Gateway and proxy HTML error pages are markup, not an explanation.
+  if (!text || /^<(?:!doctype|html)/i.test(text)) return fallback
+  return `${fallback}: ${text.length > MAX_BODY_CHARS ? `${text.slice(0, MAX_BODY_CHARS)}…` : text}`
 }
 
 const statusError = (response: HttpClientResponse.HttpClientResponse) =>

packages/ai/test/executor.test.ts

@@ -273,10 +273,39 @@ describe("RequestExecutor", () => {
       expectAIError(error)
       expect(error.reason).toMatchObject({ _tag: "InvalidRequest" })
       expect("classification" in error.reason ? error.reason.classification : undefined).toBeUndefined()
-      expect(error.message).toBe("Provider request failed with HTTP 400")
+      expect(error.message).toBe("Provider request failed with HTTP 400: invalid parameter")
     }).pipe(Effect.provide(fixedResponse("invalid parameter", { status: 400 }))),
   )
 
+  it.effect("shows unrecognized provider error bodies", () =>
+    Effect.gen(function* () {
+      const executor = yield* RequestExecutor.Service
+      const error = yield* executor.execute(request).pipe(Effect.flip)
+
+      expect(error.message).toBe('Provider request failed with HTTP 401: {"detail":"Invalid API Key"}')
+    }).pipe(Effect.provide(fixedResponse('{"detail":"Invalid API Key"}', { status: 401 }))),
+  )
+
+  it.effect("truncates long unrecognized provider error bodies", () =>
+    Effect.gen(function* () {
+      const executor = yield* RequestExecutor.Service
+      const error = yield* executor.execute(request).pipe(Effect.flip)
+
+      expect(error.message).toBe(`Provider request failed with HTTP 400: ${"x".repeat(2000)}…`)
+      expect(error.reason.body).toHaveLength(5000)
+    }).pipe(Effect.provide(fixedResponse("x".repeat(5000), { status: 400 }))),
+  )
+
+  it.effect("does not show HTML error pages", () =>
+    Effect.gen(function* () {
+      const executor = yield* RequestExecutor.Service
+      const error = yield* executor.execute(request).pipe(Effect.flip)
+
+      expect(error.message).toBe("Provider request failed with HTTP 502")
+      expect(error.reason.body).toContain("Bad Gateway")
+    }).pipe(Effect.provide(fixedResponse("<!DOCTYPE html><html><body>Bad Gateway</body></html>", { status: 502 }))),
+  )
+
   it.effect("preserves structured provider messages from large error bodies", () =>
     Effect.gen(function* () {
       const executor = yield* RequestExecutor.Service
@@ -299,7 +328,7 @@ describe("RequestExecutor", () => {
     ),
   )
 
-  it.effect("falls back when structured provider messages are empty", () =>
+  it.effect("shows the body when structured provider messages are empty", () =>
     Effect.gen(function* () {
       const executor = yield* RequestExecutor.Service
       const error = yield* executor.execute(request).pipe(Effect.flip)
@@ -308,7 +337,7 @@ describe("RequestExecutor", () => {
       expect(error.reason).toMatchObject({
         _tag: "InvalidRequest",
       })
-      expect(error.message).toBe("Provider request failed with HTTP 400")
+      expect(error.message).toBe('Provider request failed with HTTP 400: {"error":{"message":"  "}}')
     }).pipe(Effect.provide(fixedResponse('{"error":{"message":"  "}}', { status: 400 }))),
   )