Parse error from aisdk to properly show Forbidden

Author: jahooma

common/src/types/session-state.ts

@@ -68,6 +68,7 @@ export const AgentOutputSchema = z.discriminatedUnion('type', [
     type: z.literal('error'),
     message: z.string(),
     statusCode: z.number().optional(),
+    error: z.string().optional(),
   }),
 ])
 export type AgentOutput = z.infer<typeof AgentOutputSchema>

common/src/util/error.ts

@@ -187,6 +187,35 @@ export function unwrapPromptResult<T>(result: PromptResult<T>): T {
   return result.value
 }
 
+/**
+ * Parses a JSON response body string from an API error to extract structured error details.
+ * Used to extract machine-readable error codes and human-readable messages from API responses
+ * (e.g., AI SDK's APICallError includes a responseBody with the server's JSON response).
+ *
+ * Returns extracted fields, or an empty object if the responseBody is not a valid JSON string
+ * with the expected shape.
+ */
+export function parseApiErrorResponseBody(responseBody: unknown): {
+  errorCode?: string
+  message?: string
+} {
+  if (typeof responseBody !== 'string') return {}
+  try {
+    const parsed: unknown = JSON.parse(responseBody)
+    if (!parsed || typeof parsed !== 'object') return {}
+    const result: { errorCode?: string; message?: string } = {}
+    if ('error' in parsed && typeof (parsed as { error: unknown }).error === 'string') {
+      result.errorCode = (parsed as { error: string }).error
+    }
+    if ('message' in parsed && typeof (parsed as { message: unknown }).message === 'string') {
+      result.message = (parsed as { message: string }).message
+    }
+    return result
+  } catch {
+    return {}
+  }
+}
+
 // Extended error properties that various libraries add to Error objects
 interface ExtendedErrorProperties {
   status?: number

packages/agent-runtime/src/__tests__/loop-agent-steps.test.ts

@@ -20,6 +20,7 @@ import {
   mock,
   spyOn,
 } from 'bun:test'
+import { APICallError } from 'ai'
 import { z } from 'zod/v4'
 
 import { loopAgentSteps } from '../run-agent-step'
@@ -931,4 +932,89 @@ describe('loopAgentSteps - runAgentStep vs runProgrammaticStep behavior', () =>
       expect(llmCallCount).toBe(0)
     })
   })
+
+  describe('API error handling', () => {
+    it('should propagate error code and server message from 403 APICallError responseBody', async () => {
+      const llmOnlyTemplate = {
+        ...mockTemplate,
+        handleSteps: undefined,
+      }
+
+      const localAgentTemplates = {
+        'test-agent': llmOnlyTemplate,
+      }
+
+      // Mock promptAiSdkStream to throw an APICallError with a 403 status
+      // and a responseBody containing the server's structured error
+      loopAgentStepsBaseParams.promptAiSdkStream = async function* () {
+        throw new APICallError({
+          statusCode: 403,
+          message: 'Forbidden',
+          url: 'https://api.codebuff.com/v1/chat/completions',
+          requestBodyValues: {},
+          responseBody: JSON.stringify({
+            error: 'free_mode_unavailable',
+            message: 'Free mode is not available in your country.',
+          }),
+          isRetryable: false,
+        })
+      }
+
+      const result = await loopAgentSteps({
+        ...loopAgentStepsBaseParams,
+        agentType: 'test-agent',
+        localAgentTemplates,
+      })
+
+      expect(result.output.type).toBe('error')
+      if (result.output.type === 'error') {
+        // Should use the server's message, NOT the generic "Forbidden"
+        expect(result.output.message).toBe('Free mode is not available in your country.')
+        // Should NOT have the 'Agent run error: ' prefix since message came from responseBody
+        expect(result.output.message).not.toContain('Agent run error:')
+        // Should propagate the error code so the CLI can match on it
+        expect(result.output.error).toBe('free_mode_unavailable')
+        // Should propagate the status code
+        expect(result.output.statusCode).toBe(403)
+      }
+    })
+
+    it('should prefix with "Agent run error:" when responseBody has no parseable message', async () => {
+      const llmOnlyTemplate = {
+        ...mockTemplate,
+        handleSteps: undefined,
+      }
+
+      const localAgentTemplates = {
+        'test-agent': llmOnlyTemplate,
+      }
+
+      // APICallError with no responseBody
+      loopAgentStepsBaseParams.promptAiSdkStream = async function* () {
+        throw new APICallError({
+          statusCode: 500,
+          message: 'Internal Server Error',
+          url: 'https://api.codebuff.com/v1/chat/completions',
+          requestBodyValues: {},
+          responseBody: undefined,
+          isRetryable: true,
+        })
+      }
+
+      const result = await loopAgentSteps({
+        ...loopAgentStepsBaseParams,
+        agentType: 'test-agent',
+        localAgentTemplates,
+      })
+
+      expect(result.output.type).toBe('error')
+      if (result.output.type === 'error') {
+        // Should have the prefix since there's no server message
+        expect(result.output.message).toContain('Agent run error:')
+        expect(result.output.message).toContain('Internal Server Error')
+        // No error code since responseBody wasn't parseable
+        expect(result.output.error).toBeUndefined()
+      }
+    })
+  })
 })

packages/agent-runtime/src/run-agent-step.ts

@@ -2,7 +2,7 @@ import { AnalyticsEvent } from '@codebuff/common/constants/analytics-events'
 import { supportsCacheControl } from '@codebuff/common/old-constants'
 import { TOOLS_WHICH_WONT_FORCE_NEXT_STEP } from '@codebuff/common/tools/constants'
 import { buildArray } from '@codebuff/common/util/array'
-import { AbortError, getErrorObject, isAbortError } from '@codebuff/common/util/error'
+import { AbortError, getErrorObject, isAbortError, parseApiErrorResponseBody } from '@codebuff/common/util/error'
 import { serializeCacheDebugCorrelation } from '@codebuff/common/util/cache-debug'
 import { systemMessage, userMessage } from '@codebuff/common/util/messages'
 import { APICallError, type ToolSet } from 'ai'
@@ -1069,8 +1069,16 @@ export async function loopAgentSteps(
     )
 
     let errorMessage = ''
+    let errorCode: string | undefined
+    let hasServerMessage = false
     if (error instanceof APICallError) {
       errorMessage = `${error.message}`
+      const parsed = parseApiErrorResponseBody(error.responseBody)
+      if (parsed.errorCode) errorCode = parsed.errorCode
+      if (parsed.message) {
+        errorMessage = parsed.message
+        hasServerMessage = true
+      }
     } else {
       // Extract clean error message (just the message, not name:message format)
       errorMessage =
@@ -1101,8 +1109,9 @@ export async function loopAgentSteps(
       agentState: currentAgentState,
       output: {
         type: 'error',
-        message: 'Agent run error: ' + errorMessage,
+        message: hasServerMessage ? errorMessage : 'Agent run error: ' + errorMessage,
         ...(statusCode !== undefined && { statusCode }),
+        ...(errorCode !== undefined && { error: errorCode }),
       },
     }
   }

sdk/src/run.ts

@@ -15,6 +15,7 @@ import {
 import { toolNames } from '@codebuff/common/tools/constants'
 import { clientToolCallSchema } from '@codebuff/common/tools/list'
 import { AgentOutputSchema } from '@codebuff/common/types/session-state'
+import { parseApiErrorResponseBody } from '@codebuff/common/util/error'
 import { cloneDeep } from 'lodash'
 
 import { getErrorStatusCode } from './error-utils'
@@ -516,25 +517,13 @@ async function runOnce({
 
     // Extract structured error details from the API response body
     // (e.g., AI SDK's AI_APICallError includes a responseBody with the server's JSON response)
-    let errorCode: string | undefined
     const responseBody =
       error && typeof error === 'object' && 'responseBody' in error
         ? (error as { responseBody: unknown }).responseBody
         : undefined
-    if (typeof responseBody === 'string') {
-      try {
-        const parsed: unknown = JSON.parse(responseBody)
-        if (parsed && typeof parsed === 'object') {
-          if ('error' in parsed && typeof (parsed as { error: unknown }).error === 'string') {
-            errorCode = (parsed as { error: string }).error
-          }
-          if ('message' in parsed && typeof (parsed as { message: unknown }).message === 'string') {
-            errorMessage = (parsed as { message: string }).message
-          }
-        }
-      } catch {
-        // responseBody wasn't valid JSON; keep original errorMessage
-      }
+    const { errorCode, message: parsedMessage } = parseApiErrorResponseBody(responseBody)
+    if (parsedMessage) {
+      errorMessage = parsedMessage
     }
 
     resolve({